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

Goes well beyond the annotations: discovery is asynchronous with a polling contract, re-adding the same URL is non-destructive and returns the existing record (consistent with idempotentHint=true), and the 409 response carries an active_competitor_id for concurrent discovery. This is exactly the operational context an agent needs before firing a mutation.

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?

Four tight sentences, front-loaded with the action then the required follow-up, then edge cases (re-add, 409), then the sibling pointer. No filler and nothing repeated from the 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?

Covers the full lifecycle for a 3-param mutation with no output schema: what is created, that it is async, how to poll, and the failure mode. The only gap is the shape of a successful response (e.g. the new competitor id), which the agent must infer from get_competitor.

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

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

Schema coverage is 100%, so the schema already documents url, workspace_id, and monitor_types, making 3 the baseline. The description reinforces the URL semantic ('homepage URL') and implies the default page-type set, but never names monitor_types or notes that the discovery list can be narrowed, so it adds only marginal meaning.

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+key: 'Add a competitor to a workspace by homepage URL', then scopes what happens next (discovery of pricing, docs, blog, changelog). It is clearly distinguished from siblings create_monitor and get_competitor, so an agent can tell exactly what this does 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 names the follow-up tool ('poll get_competitor until discovery_status is completed') and the alternative for a different intent ('To watch one specific page, use create_monitor'). It also states the re-add case and the 409 conflict condition, 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 say readOnlyHint=false and idempotentHint=false, but the description adds context the annotations cannot: each call burns one of the monthly quota, a too-recent call returns 429 refresh_throttled, and results are asynchronous. These are the exact operational constraints an agent needs before invoking a metered, non-idempotent 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?

Four short sentences, front-loaded with what the tool does, followed by cost, error behavior, async retrieval, and the workspace-wide alternative. Every sentence carries distinct operational information.

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, and the description compensates by stating that results arrive asynchronously and naming the tools that return them. Combined with the quota and 429 disclosure, an agent has everything needed to call and follow up 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 100% and the single monitor_id parameter is already documented as coming from list_monitors or list_competitors. The description only says 'one monitor' without adding format, type, or lookup guidance, so 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 with explicit scope: 'Queue an immediate check of one monitor.' The 'one monitor' scope immediately separates it from refresh_workspace, so an agent can place it 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 the alternative and the condition that selects it ('To check every monitor in a workspace, use refresh_workspace') and tells the agent what to do with the result ('read them later with list_changes or get_monitor'). That is explicit when-to-use and post-call routing, not 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 readOnlyHint=false, destructiveHint=false, openWorldHint=true and, importantly, idempotentHint=false. The description adds that the competitor must already exist, which is useful precondition context, but it does not explain what happens on duplicate calls (given non-idempotency) or what creating a monitor returns.

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, the core capability is front-loaded, and the second sentence is purely a routing rule. No filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation with no output schema, the annotations plus full schema coverage cover most of what an agent needs. The remaining gap is what creation produces and how duplicates behave given idempotentHint=false, which the description never addresses.

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

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

Schema coverage is 100% and the cadence and monitor_type parameters carry enums plus their own cost/quota notes, so the schema does the heavy lifting. The description only contextualizes the url parameter implicitly ('one specific page'); 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 and resource — watch one page of an existing competitor — and immediately scopes it with example page types (pricing, docs). It explicitly distinguishes itself from add_competitor, so an agent can route correctly 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?

Names the alternative (add_competitor) and the exact condition that selects it: when the competitor is new and pages must be discovered. It also implies when-not for this tool (pages discovery already found) via 'that discovery missed.'

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 non-readonly, non-idempotent, non-destructive, so the safety profile is covered. The description adds genuinely non-structured context: a plan-based workspace cap that surfaces as HTTP 422, and why product_url changes downstream output (why_it_matters). It stops short of saying what the call returns on success.

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?

Four short sentences, front-loaded with the core action, then the param rationale, then the failure mode, then the sibling routing. No filler or restated 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?

There is no output schema, so the description carries the return-value burden and only partially meets it — it discloses the 422 failure but not the shape of a successful response (e.g. workspace id). For a 2-param creation tool the rest of what an agent needs is present.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond the schema by explaining the purpose of product_url — it makes why_it_matters explain each change relative to your product — which is motivation the schema text does not carry.

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 workspace") plus the scoping unit ("one product or market"), which immediately distinguishes it from list/update/delete siblings. An agent can tell what it produces 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 routes the alternative case away: "To rename or change an existing workspace, use update_workspace." It also gives conditional guidance for the optional param (set product_url to your own product). Both when-to-use and when-not-to-use are 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 already flag destructiveHint=true and idempotentHint=true, but the description adds information annotations cannot express: the exact cascade scope (monitors, snapshots, changes) and that deletion is irreversible. This is the behavioral context an agent needs before calling a destructive tool.

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

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

Two short sentences, zero waste. The destructive scope is front-loaded and the safe alternative follows immediately.

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 single-parameter destructive tool with rich annotations and no output schema, the description covers everything an agent needs: what is destroyed, irreversibility, and the safer alternative. Nothing material 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?

Only one parameter, and the schema already documents it fully (100% coverage) including the source of the id (list_competitors or add_competitor). The description adds no parameter-level detail, so the baseline 3 for schema-covered params 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 and resource ("Permanently delete a competitor") and immediately scopes the operation to its cascade effects (monitors, snapshots, changes). An agent can distinguish this from delete_monitor or update_competitor 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 names the alternative and the condition that selects it: "To stop checks and keep history, use update_competitor with status paused." This is a clear when-not-to-use rule pointing at a named sibling.

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 structurally. The description adds genuinely new context: the deletion is permanent, irreversible, and cascades to snapshots and changes — the cascade is the key operational fact not in the annotations. It stops short of mentioning auth requirements or confirmation 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?

Two sentences, no filler. The irreversible cascade is stated first and the safer alternative second, which is the correct ordering for a destructive action.

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 single-parameter destructive tool with full annotation coverage and no output schema, everything an agent needs is present: what is destroyed, that it cannot be undone, and the recommended non-destructive path. Nothing material is missing.

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

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

Schema coverage is 100% and the single parameter already documents its source ("Monitor id from list_monitors or list_competitors"). The description adds no further meaning about the identifier, so baseline 3 applies — the schema does all the work here.

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 ("Permanently delete one monitor") and adds the cascade scope ("with its snapshots and changes"), which distinguishes it from sibling deletes like delete_competitor and from update_monitor. An agent can identify the operation and its blast radius 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?

"To stop checks and keep history, use update_monitor with status paused" names the alternative tool, the exact parameter value, and the condition under which it should be preferred. Combined with "Cannot be undone," the agent has both a routing rule and a decision constraint.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true, and the description goes further by stating the operation cannot be undone, enumerating exactly what gets destroyed, and documenting a concrete failure mode with its status code. That is behavioral context beyond what the structured fields provide.

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 sentences, all earning their place: destructiveness first, then the error condition, then the escape hatch. Front-loaded and free of restatement.

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 one parameter, the description covers irreversibility, cascade scope, and the 409 path. It stops short of noting permission requirements or what the success response looks like, which would fully close the loop for a destructive 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 100% and the single workspace_id parameter is already described as coming from list_workspaces or create_workspace. The description adds nothing about the parameter itself, so the baseline 3 is appropriate for a one-param tool where the schema does the work.

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 gives a specific verb and resource ('Permanently delete a workspace') and spells out the exact cascade scope (competitors, monitors, snapshots, changes). That scope statement alone distinguishes it from delete_competitor and delete_monitor, which share the deletion verb but not the cascade.

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 alternative ('To stop checks and keep history, use update_workspace with status paused') with the condition that selects it, plus the blocking condition (409 discovery_in_progress) under which the call will fail. An agent has everything it needs to choose between the two paths.

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 (readOnlyHint=true, openWorldHint=false), so the remaining burden is small. The description still adds real value by disclosing what the response contains and that evidence (captured page, raw diff) is opt-in via include, which implicitly signals payload growth. It does not mention pagination or size limits, so it is not fully transparent.

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

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

Two sentences, front-loaded with the core action and return shape, followed by one sentence on the optional parameter. 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?

For a read-only single-entity fetch with no output schema, the description covers the action, the main response contents, and the optional expansions — enough for an agent to call it correctly. Missing only minor operational detail (what happens with an invalid id, response size behavior when including raw_diff).

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

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

Schema coverage is 100%, so both change_id and include (including all three enum values) are fully documented in structured fields. The description only restates that include adds captured page or raw diff as evidence, which marginally clarifies intent but adds no syntax or format detail beyond the schema. 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 and resource ('Get one change') and enumerates the returned payload (why_it_matters, field-level diffs, related clusters), which separates it from the list-style sibling list_changes. It stops short of naming that sibling explicitly, so the differentiation is implied rather than stated.

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?

Usage is only implied: the verb 'Get one' plus the required id suggest fetching a single known change, and the include parameter hints at opt-in expansion. There is no explicit 'use this instead of list_changes/get_digest' guidance or any precondition stated in the description itself (the id source hint 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 declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful context beyond that: the response embeds monitors and discovery fields, and the tool is intended to be polled repeatedly until a terminal status. It stops short of stating what a pending status looks like or whether polling is rate-limited.

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

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

Two sentences, front-loaded with the purpose and then the operational instruction. No redundant restatement of the tool name or 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?

No output schema exists, and the description compensates by naming the embedded monitors and discovery fields plus the discovery_status terminal values. What the discovery fields actually contain is left implicit, a minor gap for a read tool with full annotation coverage.

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?

Only one parameter and schema description coverage is 100%, with the schema already stating the id comes from list_competitors or add_competitor. The description adds no format or type detail on top of 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 and resource ("Get one competitor") and discloses the payload composition (monitors and discovery fields), which implicitly contrasts with the sibling list_competitors. An agent can tell immediately this is a single-record read that returns nested data.

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

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

Gives an explicit workflow: use after add_competitor and poll until discovery_status is completed or failed. That is concrete when-to-use guidance tied to a sibling. It does not cover the plain lookup case versus list_competitors, which keeps it short of a 5.

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?

With readOnlyHint and openWorldHint already declaring the safety profile, the description adds real value by disclosing the shape of the aggregate result (review queue with why_it_matters, activity map by competitor, top opportunities) — important since there is no output schema. It does not mention cost, latency, or result-size limits for what is presumably a generated summary.

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 with the resource and scope front-loaded, the returned sections enumerated, then the sibling alternative last. 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?

Covers purpose, returned content, and the sibling boundary, which is sufficient for a read-only two-parameter tool whose input schema is fully annotated. Missing only operational caveats such as summary generation time or bounds on period cost.

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 period enum with its 7d default is fully documented in the schema. The description only echoes "for a period" and adds no format, default, or workspace-id guidance, so 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 and resource ("Get a workspace summary") plus the scope ("for a period"), and enumerates the three constituent sections returned. It explicitly distinguishes itself from list_changes, 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?

Names both a positive use case ("Use it for briefings") and the alternative ("to page through individual changes, use list_changes"). No explicit when-not conditions beyond that single alternative, but the routing signal is concrete.

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 closed-world, so safety is covered, and the description adds real content on top: what the response contains (settings, health, last run) and that include pulls evidence from the 'latest successful capture' rather than the latest attempt. It does not mention pagination or failure behavior, but for a read tool of this shape it goes beyond the annotations.

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

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

Two sentences, no filler, with the core fetch described first and the optional expansion second. Everything present earns its place.

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 takes on the job of sketching the return shape, which it does via 'settings, health, and last run' plus the optional capture evidence. A brief note on when the capture may be absent would round it out, but an agent has enough to call 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 100%, so both parameters are already documented, and the description only restates 'include' at a high level. It adds the 'latest successful' qualifier usefully but omits the raw_diff option entirely, so it neither compensates nor fully mirrors the schema. Baseline 3 fits.

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 ('Get one monitor') plus the payload the agent receives: settings, health, and last run. The singular scope implicitly separates it from list_monitors, but no sibling is named explicitly, so the differentiation is inferred rather than stated.

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?

Usage is implied by the singular fetch framing and by the optional 'include' expansion, but the description never says when to prefer this over get_change, list_monitors, or check_monitor, nor does it state any preconditions. Adequate, not instructive.

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 openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing ordering (newest first), the cursor pagination contract (page with after set to next_cursor), and the presence of meta.counts inbox totals. It does not cover what happens if since and after are combined or any limits beyond the schema's own page-size note.

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 dense sentences with no filler. The core action and ordering lead, pagination and response shape follow, and the alternative routing closes it out.

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 names the returned fields and meta.counts, which the agent could not otherwise know. Remaining gaps are minor: how multiple filters interact and whether since and after can be combined are left to inference.

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 every one of the eight parameters is already documented in structured data. The description's pagination hint ('page with after set to next_cursor') restates the schema's own wording rather than extending it, and it adds no syntax detail for since, min_severity, or review_status. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource (list detected competitor changes) plus scope (in a workspace), ordering (newest first), and the fields returned. It is immediately distinguishable from get_change and get_digest, which are named explicitly.

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?

Names two alternatives with the exact condition that selects each: get_digest for a summarized period, get_change for evidence on a single change. This is explicit when-to-use routing rather than implied 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 cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds real value by disclosing that results nest monitors under each competitor with last_run, which no output schema provides. It stops short of noting ordering, pagination, or behavior for workspaces with no competitors.

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 action and return shape, and the routing guidance follows immediately. Slight overlap between the enumerated fields in sentence one and the 'overview of what is tracked' framing in sentence two, but nothing is wasted or buried.

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 single-parameter read tool with no output schema, the description covers what is returned at a useful level of detail and how it differs from the sibling. Minor gaps: no indication of ordering, volume, or whether discovery_status values have meaning an agent should act on.

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?

Only one parameter (workspace_id) and schema description coverage is 100%, with the schema already pointing to list_workspaces/create_workspace as its source. The description adds no additional semantics about the parameter, 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 and resource ('List the competitors in a workspace') and even sketches the return shape (discovery_status, nested monitors with last_run). It explicitly distinguishes itself from the closest sibling, list_monitors, so an agent can choose 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 a positive condition ('Use it for an overview of what is tracked') and names the alternative plus its selecting condition ('to list monitors alone or filter them by competitor, use list_monitors'). This is the when/when-not/alternative pattern done 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 declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds value by enumerating the returned fields, which tells the agent what it can screen on (status, health, last_run). It stops short of describing result ordering, pagination, or what an empty/failing list looks like, so it isn't fully complete.

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

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

Two tight sentences, front-loaded with the core action and scope, followed by purpose and the sibling redirect. No repetition of the title and nothing that could be cut.

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 listing the returned fields, and it covers the required workspace scope plus the optional competitor filter. Minor gaps remain around pagination/limits and behavior when no monitors exist, which a listing tool at this scale would ideally note.

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 explains that workspace_id comes from list_workspaces/create_workspace and that competitor_id narrows to one competitor. The description paraphrases the optional competitor filter but adds no format or edge-case detail beyond the schema, 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 and resource ('List the monitors in a workspace'), the optional competitor scoping, and the exact fields returned (URL, type, cadence, status, health, last_run). It also explicitly distinguishes itself from list_competitors, so an agent can separate the two 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?

Gives concrete use cases ('find a monitor_id or spot failing monitors') and names the alternative path for competitors whose monitors are nested ('use list_competitors'). Both the when-to-use and the when-to-use-something-else are stated outright.

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 openWorldHint=false, so safety is covered; the description adds useful behavioral context by describing what the response payload contains (counts and max severity), which shapes downstream decisions. It does not discuss ordering, scale limits, or empty-workspace behavior, which keeps it below 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?

Three short sentences, none redundant: purpose and payload first, then the routing hint, then the alternative. Front-loaded and tight 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 carries the return-value burden and does list the salient fields, which is enough to call and interpret the result. Minor gaps remain — ordering, volume expectations, and what an empty list means — but nothing blocks 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?

The tool takes zero parameters, so the baseline of 4 applies; there is no parameter semantics to get wrong or explain. Nothing in the description misrepresents the parameterless nature of the call.

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 and resource ('List all your workspaces') and enumerates the key fields returned (competitor/monitor counts, needs_review_count, highest unreviewed severity). This clearly distinguishes it from get_digest, which is explicitly framed as single-workspace activity.

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?

'Start here to find a workspace_id' gives a concrete entry-point instruction, and 'For one workspace's recent activity, use get_digest' names the alternative and the condition that selects it. Both when-to-use and when-to-use-something-else are covered.

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?

Adds substantial context beyond annotations: quota consumption ('one monthly check'), skip behavior for recently checked monitors (with skipped_ids returned), and a runtime error condition ('Returns 409 while discovery is running'). These are exactly the operational details an agent needs when invoking the tool.

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?

Four sentences with zero waste: core action first, then quota and skip behavior, then error condition, then alternative routing. Every sentence adds distinct value and is front-loaded with the main purpose.

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 two-parameter tool with annotations covering safety and no output schema, the description covers quota impact, skip semantics, error behavior, and alternative usage. Nothing critical is omitted 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 100%, so both workspace_id and competitor_id are already well described in the schema. The description only restates the competitor_id condition ('or for one competitor when competitor_id is set') without adding syntax or format details beyond the schema. 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 action (queue immediate checks) on a specific resource (active monitors in a workspace) and scopes it with an optional competitor filter. It explicitly contrasts with the sibling check_monitor for single-monitor use, so an agent can distinguish it 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?

Explicitly communicates when to use this tool (workspace-wide or filtered by competitor) and names the alternative for the single-monitor case ('For a single monitor, use check_monitor'). No inference is needed to choose between them.

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=false, destructive=false, and idempotent=true, so safety is largely covered. The description adds real value beyond them by disclosing that the status change is reversible ('unreviewed to put it back in the inbox') and what each state means semantically. It stops short of stating that only review_status is touched or what happens for an invalid change_id.

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 front-loaded sentence with the action first and the three status options after. No filler, and every clause carries information an agent needs to pick a 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?

With only two required params, full schema coverage, an enum, and annotations covering the safety profile, the description covers what an agent needs to invoke it correctly. It could still mention that other change fields are untouched and where change_id comes from, but these are minor gaps given the schema already names list_changes and get_digest as id 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% and both parameters, including the enum, are fully documented in the schema. The description's gloss on the three status values largely duplicates the schema's own enum descriptions, so it adds little semantic depth. Baseline 3 applies when the schema does the heavy lifting.

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

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

The verb 'triage' is paired with a specific resource ('a change') and the exact field being mutated ('review_status'), so an agent knows precisely what the tool does. It is clearly distinct from the read-oriented siblings get_change and list_changes without needing to name them.

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 concrete selection criteria for each status value: 'acknowledged when it is relevant, dismissed when it is noise, or unreviewed to put it back in the inbox'. That is clear usage context, though it never names alternatives (e.g., 'use get_change first to inspect details') or states 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 declare idempotentHint=true and destructiveHint=false, so safety is covered. The description adds that the effect fans out across every monitor of the competitor and that 'History is kept', which is useful context for the pause path. It doesn't mention the plan/cadence constraint (422 cadence_not_allowed), but the schema does, so the gap is small.

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, scope stated first, sibling routing second, and no filler. Every sentence carries distinct information.

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 3 parameters, full schema coverage, and no output schema, the description supplies what the schema cannot: the bulk scope over monitors, history retention, and the sibling routing rules. 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% and both enums are documented inline, including the cadence billing/minimum-plan caveat. The description adds no parameter-level detail beyond what the schema already provides, 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?

The first sentence states a specific verb (set/pause/resume), the exact resource (every monitor of one competitor), and the two mutable fields (cadence, status). It distinguishes itself from update_monitor and update_workspace by naming both, so an agent can route 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?

Explicitly states the boundary cases: 'To change a single monitor, use update_monitor; for a whole workspace, use update_workspace.' Both alternatives and the conditions that select 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 declare readOnlyHint=false, idempotentHint=true and destructiveHint=false; the description adds real context beyond them by explaining that setting status to paused halts checks but preserves history, which is the main side effect an agent needs to reason about. It doesn't say whether omitted fields keep their current values, but nothing contradicts 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?

Three short sentences, front-loaded with the resource and mutable fields, then a status-specific rule, then a sibling pointer. No filler; every sentence earns its place.

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 partial-update mutation with full schema coverage and a non-destructive idempotent annotation profile, the description covers scope, alternative routing, and the key status side effect. Only gap is whether unmentioned fields are left untouched on a partial update, which is a minor omission here.

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%, with enums and per-parameter notes (including the 422 cadence_not_allowed case), so the schema carries the semantics. The description only restates the field list and duplicates the paused explanation, adding little new meaning beyond structured data.

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 (change) plus the exact set of mutable fields on a single monitor, and explicitly distinguishes itself from the bulk sibling update_competitor. An agent can tell it apart from create_monitor/delete_monitor 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?

Names the alternative tool and the condition that selects it ("To change every monitor of a competitor at once, use update_competitor"). Also gives a concrete usage rule for the status field (pause to stop checks while keeping history). No explicit when-not-to-use, but the routing guidance 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 cover the safety profile (idempotent, non-destructive, not read-only), and the description adds genuinely new behavior: all-or-nothing validation ('nothing is written if any field is invalid') and that pausing retains history. It stops short of describing the response payload, but the mutation semantics are well disclosed.

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 sentences, no waste: capability first, then the write-safety rule, then the sibling-routing guidance. Every clause carries information an agent needs before calling.

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 4-param, fully documented mutation tool this is effectively complete, covering scope, atomicity, and alternatives. The only unaddressed element is what a successful update returns, a minor gap given no output schema exists.

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 the partial-update contract ('send only the fields to change') that governs how all four parameters interact, which the per-field schema text does not state as a whole.

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 and enumerates exactly what can change: rename, set/clear product_url, pause/resume monitors. It distinguishes itself from delete_workspace and update_competitor by name, so an agent can route 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?

It gives explicit when-to-use guidance ('prefer it over delete_workspace' for pausing) and names the alternative for the narrower case ('To pause one competitor, use update_competitor'). Both the selection condition and the exclusion are stated outright.

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