Reqbeat Hiring Signals

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

Beyond the annotations, it explains idempotency, identical errors for foreign versus nonexistent ids, freeing a watch-limit slot, never being billed, blank-key signup behavior, and plane-session ownership. This is rich behavioral disclosure and does not contradict 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 and mostly information-bearing, with no filler. The 'WHEN' phrasing is slightly awkward and the final plane-session sentence is cryptic, but overall the structure is acceptable.

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, it provides an input/output example, error semantics, idempotency, side effects, billing behavior, auth guidance, and a plane-session caveat. An agent has enough context to invoke and interpret the call 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?

The watch_id parameter is given real meaning by referencing where it comes from, showing an example mapping, and explaining error behavior. The plane_api_key parameter has schema-level description coverage, so the description does not need to fully repeat 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?

The description clearly identifies the action as cancelling a watch that should stop firing, and references the watch id returned by watch_company or list_watches. The example makes the operation unambiguous and distinguishes it from creating or listing watches.

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 opening phrase 'WHEN a watch should stop firing' gives a direct condition for using the tool. It also clarifies ownership requirements by saying an id that is not one of your watches is an error, but it does not explicitly name a sibling alternative to avoid.

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 read-only, idempotent, non-destructive, and open-world behavior, and the description adds rich behavioral detail: exact domain matching with URL example, name matching up to five candidates with confidence scores, empty-list-not-error behavior, no hiring signal, free/demo credential mode, and no billing.

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 but every sentence adds value. The critical when-to-use condition is front-loaded, followed by parameter behavior, return shape, edge cases, and cost/auth notes. No filler or repetition.

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 no output schema, the description enumerates the returned fields and the empty-list behavior. It also covers error rules, demo authentication, billing, and directs the agent to is_hiring for hiring signals. Nothing essential 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 description coverage is only 33%, but the description compensates fully: it explains domain accepts bare host or full URL and matches exactly, name returns up to five candidates with confidence levels, and both/neither is an error. It also documents the deprecated plane_api_key in the schema itself.

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 names a specific verb and resource: find a company from its website or name when only that is known. It explicitly contrasts with every company-scoped sibling tool that requires company_id, so an agent can tell exactly when this tool applies.

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 triggering condition: the agent has a company website or name but not company_id. It also gives precise invocation rules (exactly one of domain or name). It does not name alternative non-company-scoped tools, but the context is specific enough to route correctly.

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 indicate read-only, idempotent, open-world. The description adds important context beyond annotations: billing ('empty page bills nothing', 'one change unit is metered per event returned'), event ordering, cursor mechanics, and free-tier freshness behavior. No contradictions.

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 adds information: purpose, cursor usage, billing, filters, limit, free-tier, sibling relationship. The most critical scoping and usage info is front-loaded. Slightly dense, but no wasted words.

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 covers the main concerns: cursor, billing, filters, and push/pull distinction. It does not specify the structure of each event object beyond naming event types, and idempotency_key remains undocumented, but the operational behavior is fully covered.

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 burden. It clarifies `since` (event_seq > since), `limit` is bounded, and filters by `company_id` or one exact `event_type`. However, `idempotency_key` is not addressed in the description, leaving that param semantically 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?

Description opens with a precise definition: 'The change feed, not a search: ledger events ... with event_seq > since, ascending, plus next_cursor.' It identifies the resource (ledger events) and the operation (change feed retrieval), and explicitly distinguishes itself from a search and from watch_company. This clearly separates it from sibling tools.

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?

Provides explicit guidance: 'Replay with next_cursor instead of polling or re-searching' and 'limit is bounded -- page with the cursor rather than raising it.' It names the alternative watch_company for push-based delivery via webhook, so an agent knows when to choose this pull-based tool.

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 and idempotentHint, but the description adds valuable non-obvious behavior: deduplication across boards, freshness flooring, rejection of plain role names for `function`, and rejection of oversized `limit` pages. These are exactly the kind of edge cases an agent needs to know and are not inferable from 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 three sentences with no filler. The core purpose is front-loaded, followed by two targeted parameter clarifications. It is efficient and to the point, though it could be slightly more explicit about the return format.

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 only a single required parameter, the description covers the essential behavior (what is returned, key parameter restrictions) but omits details on optional filters like `country` and the idempotency key's purpose. It is sufficient for basic invocation but not fully self-sufficient for all parameters.

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% (only plane_api_key has a description, and it's about deprecation). The description compensates for two key parameters: `function` (must be a function id, not a role name) and `limit` (bounded, rejected if too large). However, it says nothing about `country`, `company_id`, or `idempotency_key`, leaving those to the agent's inference.

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 clear resource ('active reqs') and adds scoping traits ('deduped across boards', 'ATS/board-only', 'freshness-floored') that distinguish it from sibling tools like search_jobs or get_role. The verb is implied by the name, but the description makes the exact output and filtering behavior concrete.

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 no explicit guidance on when to use this tool versus alternatives. It hints that `function` must come from prior results, implying a sequential workflow, but it never names sibling tools or states exclusions, so an agent gets little help deciding between get_open_reqs and other company-related 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds context about freshness floors, error semantics (explicit error, not empty success), billing behavior (not billed for errors), and demo mode behavior with per-IP limits. However, it doesn't detail rate limits beyond per-IP, or what happens when the limit is reached, leaving some behavioral ambiguity.

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 a single well-structured paragraph that front-loads the core purpose and key pairing, then covers error and demo modes. It is dense but not bloated; every sentence adds useful information, though a bit long. It earns a 4 for being efficient yet packed with relevant details.

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 tool's moderate complexity (4 params, no output schema, but annotations cover safety), the description provides essential usage context: scoping, error behavior, billing, and demo access. It lacks details on return format (no output schema) and specific parameter formats beyond the pair, but these are partially covered by the schema. Overall, it's sufficiently complete for an agent to invoke 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?

The schema description coverage is only 25%, so the description must compensate for the undocumented `req_key` and `company_id`. The description clarifies the pair semantics ('every `search_jobs` row already carries') and mentions `plane_api_key` is deprecated via schema, but the description doesn't elaborate on `idempotency_key` or provide syntax details for `req_key` or `company_id`. Since it partially compensates but not fully, a 3 is appropriate.

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 precisely states that this tool retrieves a single open role's details using the `company_id` + `req_key` pair, and explicitly contrasts it with `get_open_reqs` which pulls the whole company. This makes the tool's purpose unambiguous and distinct from siblings, especially `search_jobs` and `get_open_reqs`.

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 says this is the 'follow-up call for a role you hold an identifier for, instead of re-pulling the whole company with `get_open_reqs`. It also provides guidance on error conditions (non-existent, closed, or not yet fresh roles) and demo mode usage (omit header for free calls). This gives clear when-to-use vs 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?

Beyond the annotations, it discloses the crawling edge case with the exact returned shape, tells the agent to poll again later, and explicitly warns against reading crawling as 'not hiring'. This is genuinely useful behavior disclosure.

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 each sentence earns its place: core output first, usage instruction second, freshness and edge-case handling next, sibling routing last. There is no redundant restatement of the tool name or title.

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?

Since there is no output schema, the description carries the burden of explaining the return shape and edge cases, and it does: metrics, max_age behavior, crawling status, and the not-hiring interpretation. For a read-only lookup with one required parameter, 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?

With schema description coverage at only 25%, the description compensates well for company_id and max_age: company_id ties to a held company, and max_age is defined in seconds and controls freshness. It does not explain idempotency_key, though the name plus the idempotentHint make that gap lower-risk.

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 definition of the artifact: one number set for one company, enumerating reqs opened, velocity, direction, surge flag, and momentum. It also names sibling alternatives, so the agent can distinguish it from pre_action_brief and 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?

It gives explicit usage guidance: use it to rank or score a company once a company_id is already held. It also routes to pre_action_brief for the full picture and is_hiring for a cheap yes/no, leaving little 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 cover read-only, idempotent, and non-destructive traits. The description adds valuable behavioral context beyond annotations: it explains the meaning of coverage_status 'no_ats_signal' (not evidence of quietness), the signup-link response when no API key is passed, and the ATS/board-only freshness floor. This is meaningful extra disclosure without contradicting 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 a dense single paragraph, but every sentence adds necessary detail—usage context, parameter constraints, example outputs, and the sibling alternative. It is front-loaded with the primary usage scenario. Slightly longer than minimal, but no wasted words.

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 tool with no output schema, the description provides concrete output examples (is_hiring, open_req_count, coverage_status) and explains the critical nuance of the 'no_ats_signal' status. It also covers authentication fallback and the routing to the correct sibling. While it doesn't enumerate the full return structure, the examples and caveats are sufficient for correct invocation.

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%, but the description compensates well for `company_id` (must be an integer from an earlier result, not a name/domain) and `plane_api_key` (pass empty string to get signup link). It does not elaborate on `idempotency_key`, but this is a standard parameter and the description's targeted coverage outweighs the gap.

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 ('is hiring' for a company), clarifies it takes a company_id (not name/domain), and distinguishes itself from the sibling `who_is_hiring_for` by noting it is for qualifying an already-known company. The examples further pin down the exact behavior, leaving no ambiguity.

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 frames the tool as a 'cheap gate before spending a richer call' and provides a clear condition: use when the agent already holds a company and needs to qualify it. It also names the alternative `who_is_hiring_for` for finding companies, giving an explicit when-not-to-use. No exclusions are left implicit.

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, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it explains the return shape, that cancelled watches are excluded, that results are sorted newest first, that heartbeat fields are included, and that a blank key returns a signup link. It also clarifies billing ('Never billed'). This is strong added context, though it doesn't detail pagination or error cases beyond the blank-key case.

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 front-loaded with the most important usage signal ('WHEN you need to see what you are subscribed to'), then gives the return shape, then the key requirement, then the sibling distinction. Every sentence earns its place; the example payload is compact and informative. It is longer than a one-liner but each clause adds distinct value.

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 read-only list tool with no required parameters and no output schema, the description is quite complete: it covers purpose, return shape, sorting, exclusions, heartbeat semantics, auth, billing, and sibling differentiation. The only minor gaps are lack of explicit pagination behavior and no mention of error responses beyond the blank-key signup link, but these are not critical for a simple list 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 description coverage is 100% for the single parameter, and the schema already explains that plane_api_key is deprecated and should be passed via header or omitted for demo mode. The description reinforces this by saying 'Needs your key: a blank one returns a signup link,' which adds a behavioral consequence of omitting the key. Since the schema covers the parameter well, the description's marginal addition is modest but useful.

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 clear WHEN and a specific verb+resource: 'see what you are subscribed to' and explicitly contrasts with cancel_watch by noting it returns the id that cancel_watch takes. It also distinguishes itself from watch_subscriptions (plane-owned) and states it lists live watches newest first, excluding cancelled ones. This is a specific, well-scoped purpose that an agent can act on 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?

The description gives explicit usage context: use it before adding a watch or to find the id for cancel_watch. It also names the alternative watch_subscriptions and states it is plane-session only, which tells the agent when not to use this tool. The note about needing a key and demo mode further clarifies invocation conditions.

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 mark this as read-only, idempotent, non-destructive, and open-world. The description adds useful behavioral context beyond that: caching via `max_age` seconds, bounded round-trip design, compactness from section caps, and a `{job_id, status: "crawling"}` fallback when no ATS/board data exists. This is solid but does not fully detail every edge-case 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 dense but front-loaded: the first clause captures the core purpose, and each sentence earns its place by addressing content, usage, cache behavior, and alternative tool. The long list of sections is slightly heavy but not redundant.

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 of explaining return values, and it does so by listing the five included sections and the crawling fallback. It also covers usage timing and freshness semantics. It stops short of describing the full exact response shape or pagination, but it is sufficient for an agent to select and invoke the tool appropriately.

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%, so the description must compensate. It does clarify `max_age` is in seconds and ties `company_id` to an ID the agent already holds. However, it does not add meaning for `idempotency_key`, and `plane_api_key` is handled by the schema's own deprecation note rather than the 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?

The description explicitly states the tool's purpose: give an agent everything needed before acting on one company in one round-trip. It enumerates five concrete data sections, and it distinguishes itself from the sibling tool `hiring_pulse` by saying that tool is cheaper when only the velocity number is needed.

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 when-to-use guidance: 'Use it right before writing outreach or a qualification note for a `company_id` you already hold.' It also provides an explicit alternative: 'If you only need the velocity number, `hiring_pulse` is cheaper.' This is strong routing behavior.

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 mark idempotentHint=true, but the description adds material detail: same URL returns same id, secret generation behavior, secret never returned, free registration, and plane-session-only scope. No contradiction with annotations exists.

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 earns its place: purpose, prerequisite, idempotency, secret semantics, billing, and session constraint. The content is front-loaded with the core purpose and structured so an agent can quickly extract the critical usage rule.

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 lacking an output schema, the description states the returned identifier and its purpose. It covers prerequisites, retry safety, optional parameter behavior, billing, and session scope, leaving no operational gap for invoking the 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 coverage is only 33%, so the description carries the burden for `url` and `secret`. It explains `url` as the idempotency key and `secret` as an optional verification mechanism with generated fallback. The schema documents `plane_api_key`, so all parameters are meaningfully covered.

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'. It also names the downstream consumer, `watch_company`, and the key return value, `webhook_endpoint_id`, which makes the tool's role unambiguous and distinct from siblings.

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?

Provides explicit invocation guidance: 'call this first if you do not already hold one' and explains that `watch_company` follows. It also clarifies safe retry behavior via idempotency and billing implications, giving an agent clear conditions for when and how to use the tool.

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 establish readOnly/openWorld/idempotent/non-destructive, so the bar is for added context, and the description clears it decisively: ATS-only plus freshness floor, rejection-vs-empty error behavior for invalid `role` values, oversized-`limit` rejection instead of truncation, and the full demo-credential/signup-link authentication behavior. None of this is inferable from the annotations, and nothing contradicts readOnlyHint.

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 long (~200 words), but the tool has 9 parameters, pagination, error modes, and an authentication fallback that all need documenting, and every sentence adds a distinct fact with no filler. It is front-loaded with purpose and sibling routing; the weakness is the single dense paragraph, which would be easier to parse with sectioning.

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 complex tool with no output schema, it covers filtering, pagination, error behavior, and authentication, and even names key return elements (`company_id`, `req_key`, `relevance`, `next_cursor`). It falls just short of fully specifying the result row shape, and `idempotency_key` is left unaddressed, but neither gap prevents an agent from invoking the 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?

With schema coverage at only 11%, the description carries nearly the entire burden and mostly succeeds: it explains that `role` must be a function id (plain names are rejected), `geo` is a country, `q` searches titles semantically with 0-1 `relevance`, `sort` takes 'relevance' or 'recency', `cursor` comes from a prior call's `next_cursor`, and `limit` is bounded. The one real gap is `idempotency_key`, which is never explained, and `since` is named as a filter without format detail.

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: 'Flat, role-granular job search -- the individual open roles across companies.' It further specifies the filtering dimensions (`role`/`geo`/`since`) and the row granularity (one per logical req with `company_id` + `req_key`), and it distinguishes itself from a sibling by naming `who_is_hiring_for` as the company-granular reverse view.

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 explicitly routes to an alternative: 'Use `who_is_hiring_for` for the company-granular reverse view.' It also gives conditional guidance for `q` vs `role`, for `sort` (relevance is the default with `q`, recency is the alternative), and for pagination (`cursor` instead of raising `limit`), so an agent knows exactly which parameter path fits which situation.

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 description adds valuable context beyond the annotations: it discloses that the operation 'meters one watch unit,' that free keys have limited concurrent watches, that exceeding the limit raises a 402 with the same semantics as the REST route, and that cancelling frees the slot. These are meaningful behavioral disclosures beyond the raw readOnly/idempotent hints.

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: the primary action in the first sentence, a key constraint in the second, and important quota semantics in the last sentence. Every sentence earns its placer, with no verbose 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 and low parameter description coverage, the tool description needs to supply more missing operating context. It doesn't mention what the call returns, what constitutes valid event_types, how to obtain a webhook_endpoint_id (via register_webhook), or how idempotency interacts with the watch operation. This leaves material gaps for the agent.

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 carries the burden of explaining parameters. It explains webhook_endpoint_id's ownership constraint and the watch unit, but it does not clarify company_id, event_types, or why idempotency_key exists. An agent selecting the right event_types or crafting a correct idempotency request would not get enough help from this 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?

The description uses a specific verb and resource: 'Subscribe to a company's hiring events on a registered webhook.' This clearly identifies what the tool does and differentiates it from siblings like cancel_watch or list_watches by semantic context, though it never explicitly names those alternatives.

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 the use case (subscribing to hiring events) and includes prerequisites such as the webhook_endpoint_id belonging to the same customer as the authenticated key, plus quota behavior for free keys. However, it gives no explicit guidance on when to prefer this over siblings like find_company or is_hiring, or any when-not conditions.

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 mark readOnly, idempotent, and non-destructive, but the description adds substantial behavioral detail beyond that: dedup by company, geo resolution with explicit unresolvable-country errors instead of partial pages, bounded limit, per-company billing, empty results billing nothing, and demo-mode/signup-link behavior. No contradiction with 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 long but information-dense and front-loaded with the key decision ('WHEN an agent needs to FIND...'). Every sentence adds a distinct fact: matching scope, error behavior, pagination, billing, demo mode, and sibling routing. The examples at the end illustrate behavior without redundant repetition.

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 complex tool with no output schema, the description covers invocation context, parameter semantics, error handling, pagination, billing, demo credentials, and sibling routing. Minor gaps remain: `idempotency_key` semantics are not described, the behavior when both `role` and `geo` are omitted is unclear, and the API-key guidance conflicts with the schema's deprecation note. Overall, 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?

With only 14% schema description coverage, the description compensates well for `role` (free text matched against posting title, not an id), `geo` (resolved to a stored country, unresolvable values error), `limit` (bounded), `cursor` (keyset pagination), and `plane_api_key` (demo behavior). However, `idempotency_key` is not explained, and the `plane_api_key` guidance conflicts with the schema's deprecation note, so it is not 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?

The opening states exactly what the agent is doing: 'FIND the companies worth working' and describes a 'Reverse who's-hiring-for {role, geo} search.' It clearly distinguishes itself from the sibling `is_hiring` by explicitly routing yes/no lookups there, and from keyed company lookup. The verb, resource, and search direction are all specific.

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 frames when to use it: 'the sourcing step, before it knows which companies exist.' It also gives a direct alternative rule: 'Already holding a company_id and only need a yes/no? Use `is_hiring`.' It further instructs agents to page with `cursor` rather than raising `limit`, which is practical usage 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 flag readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds that it appends to outcome_labels scoped to the caller's customer and is plane-only, which is useful. However, it does not disclose idempotency implications (e.g., duplicate appends) or failure behavior, and it contradicts 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?

The description is brief and front-loaded with the core action. The second paragraph adds scoping context without redundancy. It is concise, though the jargon ('label-flywheel substrate') adds slight obscurity.

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 no output schema and low parameter coverage, this description leaves important gaps: it does not specify valid outcome values, behavior when called repeatedly (idempotency consequences), or what the tool returns on success. An agent would need to infer or probe to use 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 20% (only plane_api_key has a description). The description provides meaning for company_id (the scope of the outcome) and outcome (the conversion label), but leaves observed_at and req_key unexplained. With low schema coverage, the description should compensate more fully; it only partially does.

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 ('Write back') and resource ('a conversion outcome for company_id'), and clarifies the underlying action ('Appends to outcome_labels'). This clearly differentiates it from the sibling tools, which cover watches, company search, and hiring signals.

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 context ('Plane session only', 'reads no corpus table') that implies it is for plane-scoped outcome recording, but it does not explicitly state when to use it over alternatives or when not to use it. No alternatives are named.

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