Watchtower

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

Annotations cover the safety profile (idempotentHint=true, destructiveHint=false, readOnlyHint=false), and the description goes further by disclosing the at-least-once delivery model and the auto-ack behavior of non-peek reads. It does not discuss what happens to an already-acked or stale cursor, but the delivery semantics it does provide are substantive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences: purpose first, then the canonical workflow, then the negative case. Zero filler and the routing information is 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 and only three fully documented parameters, the description supplies everything an agent needs: the ack semantics, the paired tool, and the condition under which this call is unnecessary.

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%, so the schema already explains cursor, watch_id and client_token in detail. The description only ties 'the cursor get_changes returned' to the workflow and adds nothing about watch_id scoping or the optional token. Baseline 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?

States a specific verb and resource ('Mark changes up to a cursor as processed') and immediately distinguishes itself from the sibling get_changes by naming the peek/non-peek interaction. An agent can tell exactly what state this mutates without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly prescribes the workflow (peek, act, then ack the returned cursor) and explicitly states the exclusion: 'Not needed if you call get_changes without peek (that acknowledges automatically).' Both the when and the when-not are covered with no inference required.

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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds value beyond that by disclosing a side effect the annotations do not capture: deleting frees one of a limited number of watch slots, which explains the cost of the operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences with the action front-loaded and no filler. The staccato style ("Stop monitoring.") is slightly disjointed but every sentence contributes something and nothing is repeated.

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 destructive, two-parameter tool with no output schema and full annotation coverage, the definition covers the core effect and the slot-quota consequence. It still omits whether the watch must exist, what happens to associated data, and how to obtain watch_id, leaving an agent with gaps before calling 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 50%: client_token is described in the schema, but the required watch_id has no description beyond its uuid format. The description never mentions parameters at all, so it does not compensate for the gap or tell the agent where a watch_id comes from (get_watch/list_watches).

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 names the action ("Stop monitoring", "Delete watches") and the resource (a watch), and the title confirms it as the deletion counterpart to get_watch/list_watches. It does not explicitly name a sibling to avoid, but the verb+resource pairing is unambiguous enough for selection.

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?

"Delete watches you no longer need" implies the cleanup use case and "frees one of your watch slots" hints at a quota constraint that justifies deletion. However, there is no explicit when-not guidance, no mention of prerequisites (e.g. needing an existing watch id from list_watches), and no named alternative.

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 mark readOnlyHint=false and idempotentHint=false; the description explains why by disclosing that the default call mutates cursor state while peek=true does not — a genuinely useful trait beyond the annotations. It stops short of covering auth expectations or error/rate-limit 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?

Three tight sentences, front-loaded with the return semantics, then the empty-list signal, then the cursor/peek/since variations. 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 does convey that the result is a list of changes and that an empty list is meaningful, plus the cursor advance contract. It omits pagination signals like has_more, which the schema mentions only on limit, leaving a small gap for a cursor-based paging 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?

With 100% schema coverage the baseline is 3, but the description goes further by explaining how the default cursor position interacts with peek and since, which is meaning the schema alone does not convey. It adds no detail on limit or client_token beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — returns job changes detected since the last call, scoped to all watches or one watch. It also implicitly distinguishes itself from re-browsing careers pages and from sibling tools like search_jobs/watch_jobs.

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?

Explains the operational model clearly: default cursor advancement delivers each change once, peek=true looks without advancing, since=<cursor> replays, and an empty list means nothing changed. It does not, however, state when to prefer this over siblings such as search_jobs or how it relates to ack_changes.

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 this a read-only, non-destructive, closed-world call, so the safety profile is covered. The description adds real behavioral context beyond that: what the returned job set depends on (whether the watch was created with a url), which is the key non-obvious trait of this call.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, well front-loaded: the core behavior comes first and the usage hint second. The colon clause packing in the scope rule is dense but all of it is load-bearing, 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 correctly carries the return-value burden by naming status and open jobs. Only minor gaps remain (behavior when the id is unknown, pagination/limits), which is acceptable for a two-parameter read 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%: client_token is well documented in the schema, while watch_id carries only type/format. The description says nothing about obtaining or formatting watch_id, so it neither compensates for the gap nor adds meaning. Baseline 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?

Names a specific verb+resource ('Get a watch') and goes further by stating exactly what comes back: the watch status plus the jobs currently open that match its filters. The scope rule (board-only for URL-scoped watches, all monitored boards otherwise) makes it distinguishable from list_watches and search_jobs.

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 use case ('answer "what is open right now"') and steers the agent away from the alternative path of searching or fetching careers pages. It does not name a sibling tool by name or state when not to use it, but the routing intent is clear.

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 and destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond them: 'Read-only, no token needed', the shape of each entry, and a remediation path for missing companies. It stops short of return-format/pagination notes, but the client_token param and offset param already handle auth and paging.

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?

Purpose is front-loaded in the first sentence, followed by usage, return fields, and remediation. Dense but every sentence earns its place; the return-field enumeration is justified by the absence of an output schema.

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 compensates by naming the entry fields (name, board_url, platform, open_jobs), and it covers auth, the coverage-check use case, and how to add missing companies. Nothing essential for correct invocation is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: query is framed as a coverage check with a concrete example, and board_url is explained as the value to pass to watch_jobs as url. That cross-tool parameter linkage is value the schema alone does not convey.

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 the companies whose job boards Watchtower monitors') and immediately ties it to siblings by characterizing it as what search_jobs and watch_jobs without a url cover. An agent can distinguish it from the sibling search tools 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?

Explicitly tells the agent when to use it (pass query to check whether a company is covered, e.g. "stripe") and routes to an alternative when a company is missing (watch its board URL or careers page to add it). Both a positive trigger and a fallback path are given.

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 this a safe, read-only, non-open-world operation, so the safety burden is lifted. The description adds that only *active* watches are returned and what fields come back, but says nothing about ordering, result size, or behavior when the client has no watches.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that front-loads the verb and scope, then lists the returned fields. No filler, no restatement of the 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?

With no output schema, the description usefully tells the agent what the response contains (health, last check time, pending changes). Safety is covered by annotations and the sole optional parameter is covered by the schema, so only minor gaps (ordering, empty-state behavior) remain.

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% and the schema itself gives careful guidance on the optional client_token, including the warning never to ask the user for one. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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 (List) and resource (watches) scoped to 'your client', and enumerates what each entry carries (health, last check time, pending change count). It implicitly separates itself from the singular get_watch, but never names a sibling, so it falls short of full sibling differentiation.

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?

There is no when-to-use guidance at all: nothing explains how this differs in practice from get_watch for a single watch or how it relates to watch_jobs/delete_watch. The only usage-adjacent text lives in the schema, not the description.

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 readOnly/destructive, but the description adds material behavior beyond them: nothing is saved, no watch is created, no token is needed, and the response shape (interpreted query, jobs newest first, total, next_offset). It also documents the concrete payload fields and the precedence rule that explicit filters override the query.

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 purpose, then the usage rule, then return shape, then the field list. Every sentence is functional, though the enumeration of returned job fields and the repeated query example 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?

For a 14-parameter, zero-required, no-output-schema search tool, the description covers the calling contract: what to pass, what comes back, how pagination continues, and how filters interact. Nothing an agent needs to invoke it correctly 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 100%, so the baseline is 3; the description rises above it by adding the cross-parameter precedence rule ('Explicit filters override what the query says') and by illustrating the free-text query style. It doesn't add much beyond the schema for the granular filter semantics themselves.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Find the tech jobs open right now') plus scope ('across every job board Watchtower monitors'). It also explicitly distinguishes itself from the sibling watch_jobs, so an agent can route without comparing 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?

States the selection rule verbatim: use this for 'what is open right now'; use watch_jobs to be told about new postings later. That is an explicit when-to-use plus named alternative, with no inference required.

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 declare a write operation (readOnlyHint false), non-destructive (destructiveHint false), and open-world. The description adds substantial operational detail: persistent watch creation, JOB_ADDED/JOB_REMOVED/JOB_UPDATED events, response fields (interpreted, current_jobs, coverage), supported board endpoints, JSON-LD fallback parsing, NO_JOB_DATA rejection, and filter precedence. 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?

The core purpose and key usage routing are front-loaded in the first two sentences, and most sentences carry distinct information for a complex open-world tool. However, it is a single dense paragraph that could be more scannable for a 17-parameter operation; bullets or shorter sentences would improve readability.

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, but the description explains the response shape (interpreted, current_jobs, coverage) and the change events that follow. Combined with the annotations and a fully documented input schema, it gives an agent enough context to invoke the tool correctly across many job-board sources.

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%, so the schema already documents all 17 parameters and establishes a baseline of 3. The description adds useful cross-parameter semantics beyond the schema: the query is interpreted in the response and explicit filters override what the query says, plus url omission scopes the watch to every monitored board.

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: 'Create a persistent watch for tech jobs.' It further clarifies scope (every monitored job board) and distinguishes itself from re-running searches and from later get_changes calls. An agent can identify the tool without opening sibling 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?

Explicitly instructs to use this INSTEAD OF re-running job searches or re-checking careers pages yourself, which directly routes against search_jobs. It also explains when to pass url/urls versus omitting them, and directs the agent to get_changes for later new postings.

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