Whimbrel: Medtech Research

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

Annotations already establish readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds useful context beyond that: it takes no inputs and it returns methodology, overview, and archive scale — a return-shape disclosure that matters because there is no output schema.

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 plus a fragment; the content scope is front-loaded before the input/return facts. Every clause carries information and nothing is padded.

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 describing returns and does so at a category level ('the methodology, the overview, and the published archive scale'), though terms like 'the overview' and 'archive scale' remain somewhat abstract. Sufficient for a zero-parameter documentation 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?

The tool has zero parameters, so there is nothing to document and the baseline is 4. The description's 'Takes no inputs' correctly reinforces the empty schema without contradicting 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 names the exact subject matter the tool documents: collection method, dating, windowing, feed exclusions, and licensing/attribution. No sibling tool (find, news, company, account, etc.) covers archive methodology, so an agent can route here unambiguously.

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 content listing — you call this when you need provenance or licensing context — and 'Takes no inputs' signals it is a safe no-argument call. However, there is no explicit statement of when to use it versus siblings or when it is not needed (e.g., for actual data retrieval use find/news instead).

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

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

Goes well beyond the annotations: incremental saves preserve earlier answers ('nothing is deleted'), start_over replaces the stored profile rather than merging, preserves History, and returns changed (old values) plus change_id for undo. It even discloses return behavior with no args and the set_up_now state while onboarding is unfinished — exactly the mutation/state context destructiveHint=false and idempotentHint=true cannot convey.

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 routing rule, and the onboarding, edit, reset, undo, and read modes follow in a logical order. Density is high — long run-on sentences with parenthetical field lists and a sprawling 'With nothing passed' enumeration — but nearly every clause carries operational meaning for an 18-parameter tool.

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 tool with 18 params, no output schema, and rich annotations, the description covers the state machine (build → read-back → edits), the delete/replace semantics, undo, and the full contents of the no-arg return. Nothing an agent needs to call it safely 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?

With 61% schema coverage across 18 params, the description compensates by enumerating the mutable profile fields (firm_name, role, services, device_areas, device_classes, certifications, proof, customer_stage, territory, clients, skip_companies, accounts, notes) and explaining several-in-one-call saves. It also clarifies the step/ask_now.step/skip interplay and start_over semantics. It does not explain the meaning of undocumented fields like territory, device_areas, or certifications, so it stops short of a 5.

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

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

The opening sentence defines the scope precisely: anything about the rep's own firm — what it sells, who it serves, clients, not-a-fit companies, watches, plan usage — and the rest of the text covers the onboarding/build mode. It clearly belongs to 'our firm' data in contrast to the sibling tools that operate on outside companies (company, deep_record, find). It is a multi-purpose tool, so the purpose is a bundle rather than one verb+resource, which keeps it just short of a 5.

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

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

Explicit routing: 'Call this first for anything about the rep's own firm', plus concrete branch conditions — pass step while building, start_over for a different firm or rebuild, undo_change with a change_id to revert. It does not name an alternative tool for overlapping cases (e.g., remember is only referenced inside the schema, not the description), so there is no explicit when-not/use-instead 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?

Goes well beyond the annotations (which already state readOnlyHint=false, idempotentHint=true, destructiveHint=false) by naming the response keys the agent will see: "already" with an unchanged count, and "ambiguous" with "say_now". It also discloses the coverage boundary ("Only companies Whimbrel covers can be added") and that adding never starts a watch, which is exactly the kind of side-effect context annotations cannot convey.

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 trigger condition and then sequenced in call order: what it does, what it does not do, what happens on duplicates, what happens on ambiguity. The quoted example utterances are useful but add some bulk; overall it stays tight with no filler sentences.

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

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

With no output schema, the description carries the return-value burden and does so for the two edge outcomes (already, ambiguous) plus the coverage restriction. The happy-path success shape (what a successful add returns) is not described, a minor gap for a tool with only two 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 100%, so both parameters are already documented; the description nonetheless adds real meaning by explaining that `website` is a retry input used after an ambiguous reply for a single company. It does not restate the 50-name cap or the name-format expectation, but the schema handles those.

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 plus resource: adds companies to the rep's own target set, and it explicitly frames that set as the same one the Whimbrel app shows. It is clearly distinguishable from siblings like remove_target, list_targets and watch_company, and it even states that adding does not trigger a watch.

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

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

Opens with an explicit trigger condition ("Use this when the rep asks to add one or more companies to their targets") backed by two concrete example utterances. It also routes to the alternative ("offer in one line to watch the company too (watch_company)") and defines the fallback path when a name is ambiguous.

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 declare a non-read-only, non-destructive, non-idempotent write, and the description earns credit by explaining that exact side effect: it 'marks them seen so the next check starts from now,' which tells the agent why repeat calls differ. It stops short of covering edge cases such as empty results or permission requirements.

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 scope and side effect are front-loaded, but the middle sentence is a long comma-chained enumeration of return contents that is hard to parse in one pass. It is informative rather than wasteful, yet tighter phrasing would preserve the same signal.

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 takes on the job of describing return values (events per company, device companies per space, with date and source). Combined with the disclosed side effect, an agent has enough to call it correctly, though empty-result behavior is unstated.

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 schema already states that 'name' is a company or space, may be partial, and is optional. The description restates the same fact without adding format, matching, or ambiguity-resolution detail, so the baseline of 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 clause names the resource and scope precisely ('what is new on the rep's watches since they last checked') and enumerates the returned contents, which separates it from list_watches and mark_seen. The prose is dense and clause-heavy, but an agent can identify the operation 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?

It implies the trigger ('since they last checked') and explains that passing a name narrows the check to one watch, but it never says when to choose this over list_watches or mark_seen, nor what happens when nothing is new. Usage is inferable rather than stated.

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

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

Despite the annotations already marking this as a safe, idempotent read, the description adds substantial behavioral context: what the rundown includes, how uncovered companies are handled, and how ambiguous names return `say_now` asking for a website. This goes well beyond the annotation surface.

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 usage trigger is front-loaded, the return contents are compactly enumerated, and the fallback behavior closes the paragraph. No sentence is filler; each adds either selection guidance or behavioral expectation.

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

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

With no output schema, the description must explain what comes back, and it does: coverage rationale, product, stage, location, FDA facilities, event history with dates and sources, and rep status. It also handles uncovered and ambiguous companies, making the definition complete for an agent to invoke confidently.

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 `company`, `website`, and `events`. The description reinforces the `company` and `website` workflow but adds no meaningful detail beyond the schema, and it does not mention the `events` parameter or its default/limit.

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: it produces a rundown on one named US medical device company, including coverage status, products, stage, facilities, events, and rep status. It is clear enough to select, but it does not explicitly differentiate itself from siblings such as `account` or `deep_record`.

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 states exactly when to use the tool: user asks 'tell me about' or 'what do we know about' a named US device company. It also covers when-not scenarios (foreign importer, drug company) and the ambiguous-name fallback, telling the agent to call again with `website`.

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

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

Annotations already cover safety (readOnlyHint, idempotent, non-destructive, closed-world), and the description adds real context beyond them: the subscription/record prerequisites and a concrete enumeration of what is produced. It does not mention generation time, file size, or whether repeated calls overwrite anything, which matters for a multi-file export.

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 purpose and returns, then prerequisites, then the routing fallback. The opening phrase 'One company's company record' is slightly awkward but no sentence is wasteful.

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 enumerates the return artifacts (CSV set, research notes, import steps) and states both preconditions, which is what an agent needs to call it safely. Only minor operational details (size, timing, multi-company behavior) are 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% and the enum is already declared, so the description's restatement of 'format (hubspot or salesforce)' and 'must already have a company record' adds nothing new. Baseline 3 is appropriate 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?

Names a specific verb+resource ('One company's company record as CRM import files') and states the two inputs and the three deliverables (CSV files, research-notes document, import steps). An agent can distinguish it from deep_record, company, and find 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?

Gives concrete preconditions ('Requires an existing company record and an active Whimbrel plan') and routes the no-record case explicitly to deep_record. It does not state any case where this tool should not be used despite having a valid record, so it stops short of full when/when-not coverage.

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

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

Goes well past the annotations by disclosing quota consumption (uses one of the plan's records for the month), latency (~5 minutes), the human-confirmation gate, the >1 week staleness behavior, and the plan requirement. The annotations already signal non-read-only and open-world, so this adds real operational context; the only gap is what happens on failure or partial results.

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 what the tool returns, then the operational rules; every sentence carries a rule that would otherwise cause a wrong call. It is dense and the confirmation/staleness rules are somewhat interleaved, costing a point on structure, but nothing is boilerplate.

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

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

With no output schema, the description carries the return-shape burden and does so by naming the sections returned. It covers cost, latency, approval gating, staleness, and prerequisites, which is everything an agent needs for a slow, quota-consuming, human-gated operation.

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

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

Schema coverage is 100%, so the baseline is 3; the description nonetheless adds relational semantics the schema only implies piecewise — that refresh is inert without start_new_record true, and that domain is only needed for uncovered companies after asking the rep. That cross-parameter coupling is genuinely useful during invocation.

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

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

States a specific verb+resource: a full research rundown on one company, and enumerates the returned content (facts, named partners, dated events, evidence/source, known gaps). It also carves out the narrower mode (fact=email/clearance/trial returns a single stored fact), which separates it from lighter siblings like company or opening_line_facts.

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

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

Explicit when-to-use rules: pass domain when asking for new research, pass fact for a single stored fact, do not start a record without rep approval, pass start_new_record true only after yes, and pass refresh + start_new_record for stale records. It also routes the waiting loop to research_status rather than the rep, naming the alternative 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial beyond that: it discloses the evidence sources folded in, that results are deduped to one row per company, that the rep's own clients and non-fit companies are excluded, that ranking is by fit to what the firm sells, and the pagination contract (total, page, next_cursor, in_targets/watched).

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 trigger condition, which is good, but the middle is repetitive — the device/role/state/date filter set is stated twice in near-identical wording. Dense and informative, yet a trim of that duplicated clause would lose nothing.

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

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

For a 10-parameter, zero-required search tool with no output schema, the description does the necessary work: it explains the ranking logic, the exclusion filters, the per-company evidence/source structure, the flags, and pagination via next_cursor. Nothing an agent needs to call 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: `about` is plain words for a device/tech/space, `ask` is for requests that say more than `about`, `sort=fit` overrides about/role ordering, and `limit`/`cursor` relate to the returned next_cursor. It stops short of clarifying edge cases like `since` vs. `looking_for` interaction.

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 — finds US medical device companies — and enumerates the searchable dimensions (device/technology/space, hiring role, state, date). It also explicitly routes a related need elsewhere: recalls and CDRH warning letters live on the company record, not in this search, which separates it from the `company` sibling.

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

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

Opens with the exact user phrasing that should trigger it ('who should I reach out to', prospects, leads, targets, device areas) and explains the no-filter fallback behavior. It also carves out what NOT to use it for (recalls, warning letters) and says to tell the user rather than misread an inspection as a recall.

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 and idempotentHint=true, so the safety profile is covered. The description adds real value beyond that by delimiting the blast radius: 'The companies and their public records are not affected' and pointing to the Memory page for other profile edits. It doesn't confirm irreversibility or partial-failure behavior, keeping it from 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?

The main action is front-loaded in the first clause, and every sentence carries information. However, the first sentence is long and packs mode definitions into a dense parenthetical, which slows parsing slightly.

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

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

For a 3-parameter mutation tool with no output schema and covered annotations, this is close to complete: it describes each mode, what is and isn't destroyed, and a prerequisite lookup via account. Only the return/confirmation behavior and handling of partial vs. full deletion are unaddressed.

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 goes further by explaining the distinct effect of each parameter: companies clears status and removes from all profile lists, stop_working only removes from prospects, watches deletes by name. That nuance is not in the schema descriptions.

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 concrete verb (deletes) on a named resource (what Whimbrel keeps for this rep about a company) and then spells out three distinct modes: companies, stop_working, watches. It does not explicitly contrast itself with siblings like remember, but the per-mode breakdown makes the tool's scope unambiguous once read.

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 states the triggering condition ('when the rep asks') and gives an explicit fallback: 'If the rep did not give the exact name, read their watches from account first,' which routes the agent to a sibling tool. It stops short of stating when not to use this tool (e.g., use remember to add instead).

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: no API key is required, sign-up collects a work email and a 6-digit code sent by Whimbrel, and the app is handed a token with nothing to paste. It does not describe the returned shape when plan is omitted, but otherwise the agent knows what to expect from the interaction.

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

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

The purpose and plan semantics are front-loaded and efficient, and the 'no key is required' and team-of-5 escalation lines earn their place. The closing sentence walking through the rep entering a work email, a 6-digit code, and token handoff is end-user narration that is tangential to selecting and invoking the tool, and it dilutes an otherwise tight definition.

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 one-parameter, read-only tool with no output schema, the description covers what is returned (a sign-up link), how billing differs per plan, the omit-for-both behavior, the no-key requirement, and the team escalation path. The only real gap is that it never states the response format or whether omitting plan returns two links versus one object, but that is minor given the tool's simplicity.

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 enum parameter is already documented, so baseline is 3. The description earns above baseline by explaining the meaning behind each enum value: individual is billed monthly, individual_year is billed once a year at a lower monthly rate, and omitting returns both.

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 and resource: it returns the sign-up link for Whimbrel's single plan, along with the free-month framing. That is far clearer than the vague name 'get_access' and is unmistakably distinct from data-oriented siblings such as company, people, or deep_record. It stops short of an explicit 'use this when the user asks about pricing or sign-up' routing statement, but the purpose itself is unambiguous.

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 invocation guidance: pass plan as individual or individual_year, or omit it for both, plus an explicit exclusion routing teams of 5+ to a contact URL. What it lacks is a stated trigger condition (e.g. 'call this when the user asks how to sign up or what it costs'), which is 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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description still adds real behavioral value by disclosing sort order ('newest first') and the shape of each result entry (name, company count, ranked date) — important since there is no output schema.

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?

One dense sentence with no filler, and the identifying clause plus ordering comes before the return-field detail. The nested parenthetical ('rank_list with a name, or Rankings in the Whimbrel app') is slightly heavy but each element earns its place as an alias.

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 no parameters, the description must carry return semantics, and it does name the per-item fields and ordering. Minor gaps remain: it doesn't mention what an empty list looks like or whether the list is capped in size.

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 input schema has zero parameters, so there is nothing to document; baseline of 4 applies. The description correctly does not invent parameters and instead spends its words on return content.

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 ('The ranked sets the rep saved'), and adds scope and ordering ('newest first') plus the fields returned. The parenthetical mapping to 'rank_list' and 'Rankings in the Whimbrel app' lets an agent place it against the sibling rank_list and open_ranked_set 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?

The description implies the browsing use case ('the ranked sets the rep saved') but never says when to choose this versus open_ranked_set (view a set's contents) or rank_list (create one). Terminology disambiguation is given, but no explicit when/when-not routing, so usage is only inferred.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so safety is covered. The description adds real behavioral context beyond that: a 100-per-page cap, cursor-based pagination, default sort, and default sort ordering — the kind of operational detail an agent needs to page correctly.

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 return shape is front-loaded before the operational details, and almost every clause carries information. It is one dense paragraph with somewhat telegraphic phrasing ('Fit when Whimbrel has scored it'), which reads a little compressed rather than wasteful.

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

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

With no output schema, the description must carry the return shape, and it does — latest change date, what happened, source link, Fit, added date/location, watched flag, unseen flag. Some of those field explanations are terse enough to be ambiguous, but an agent can call and interpret the tool without further information.

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 60% (sort and watched_only carry no schema descriptions), and the description compensates: it enumerates the four sort values with 'added' as the default, defines changed_since's YYYY-MM-DD format and filter effect, and explains watched_only's semantics. Only the limit/cursor params are left to the schema, which already documents them.

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 resource (the rep's targets, i.e. companies) and enumerates what each row carries, which is far more specific than the bare name. It implicitly distinguishes itself from add_target/remove_target by being read-oriented, but never states a verb or names a sibling it replaces, so it stops short of a 5.

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?

Pagination and filtering mechanics are explained ('pass next_cursor for more', 'changed_since keeps targets with a change since then', 'watched_only keeps watched ones'), which tells the agent how to narrow results. However, there is no guidance on when to reach for this tool instead of the many siblings (find, company, account, list_watches, rank_list), so the choice is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds value beyond that by disclosing the shape of what comes back ('each company with its latest change, each space with what it covers') and that results are scoped to 'the rep' — helpful given there is no output schema. It does not cover ordering, pagination, or what an empty result means.

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 with no filler, and the resource definition is front-loaded ahead of the optional filter behavior. Every clause carries information about either the resource or the parameter.

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 optional-param, read-only listing with no output schema, the description is largely sufficient: it names the resource, the per-kind detail returned, and the filter. Missing only minor operational details such as default behavior with no kind and result ordering.

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 0%, so the description must carry the single parameter — and it does, explaining that 'kind limits it to company or space watches', which maps onto the company/space enum. The only gap is that it does not state what happens when kind is omitted (presumably both kinds are returned).

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

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

The description identifies the resource precisely: companies and spaces the rep watches, with the latest change per company and coverage per space. This reads clearly as a watch-inventory listing and is distinguishable from siblings like list_targets, check_space_watch, and watch_company, though the verb (list) is only implied by the name 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?

There is no explicit when-to-use or when-not-to-use guidance, and no routing to the closest siblings (check_space_watch, list_targets, save_space_watch, unwatch). The only usage-adjacent statement is that 'kind limits it to company or space watches', which is parameter guidance rather than tool-selection 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 declare readOnly=false, destructive=false and idempotent=true; the description still adds real value by explaining what state changes (items stop appearing as new) and by flagging the bulk case when no companies are supplied. It does not say whether the seen flag is per-rep or organization-wide, nor whether it can be reverted.

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, front-loaded with the action and effect, with the scope default last. No wasted clauses or restated name/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?

For a one-optional-parameter tool with rich annotations, the description covers purpose, effect and bulk default sufficiently. The only gap is that there is no output schema and the description says nothing about what a call returns (e.g., a count of affected targets).

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% for the single optional 'companies' parameter and the schema already says 'none marks all'. The description restates that default ('marks every target') but adds no syntax or format detail 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 ('Marks ... as seen'), names the resource ('the latest changes on the rep's targets') and the resulting effect ('no longer show as new'). It is unmistakably distinct from siblings such as list_targets, add_target and remove_target.

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?

'With no companies, marks every target' clarifies the default scope but is a parameter note rather than when-to-use guidance. No alternative tool or exclusion is named, so the agent must infer that this is the clearing counterpart to whatever surfaces 'new' 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 readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds real value beyond that by disclosing the output shape (one row per company, with dates and source links), the ranking basis ('ranked for the rep's firm'), and the geographic scope (US). It omits pagination behavior and how ranking is computed, which keeps it from 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?

The trigger condition is front-loaded in the first clause, and the second sentence packs scope, event taxonomy, and output shape efficiently. The quoted example list is somewhat long, but each example earns its place as a routing cue.

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 six optional parameters, no output schema, and annotations covering safety, the description supplies the missing pieces an agent needs: what the rows contain, that results are ranked, and that coverage is US-only. Pagination is left entirely to the `cursor`/`limit` schema fields with no prose on paging behavior, a minor gap.

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 all six parameters are already documented in the schema, and the description's example phrases ('anything new in neuromodulation', 'who got FDA clearance lately') loosely map to `about` and `days` without adding syntax or defaults. Baseline 3 is appropriate given 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 description names a specific resource and scope: recent sourced events at US medical device companies and their suppliers, covering FDA clearances, recalls, trials, funding, press and hiring, one row per company. This clearly distinguishes it from siblings like company, find, or about_the_data, which serve different lookup needs.

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 clause gives an explicit trigger ('use this when the user asks what's new in medtech') followed by four concrete example utterances that cover common phrasings. There is no when-not guidance and no named alternative tool for adjacent questions (e.g., a specific company profile), so it stops 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?

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the description's value is in disclosing what the result contains: recent events with their sources, plus rep-side matches such as service fit, closest past project, requested certification, and the angle when the company resembles existing clients. The explicit 'returns the facts, not the lines' caveat usefully sets expectations. It stops short of describing output shape or depth per fact when no output schema 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?

The core purpose and the key caveat are front-loaded, but the body is a single long run-on sentence with a nested list that is hard to parse. It is dense with real content rather than filler, yet could be split into a purpose sentence and a returned-facts sentence without loss.

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 the work of explaining return content by enumerating the fact categories and their sourcing. Combined with annotations covering safety, the main remaining gap is the missing identifier semantics for the required 'company' parameter rather than anything about the result.

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%, and the undocumented parameter is the required one: 'company' has no description in either the schema or the description, so the agent gets no guidance on whether it expects a legal name, a domain, or an internal ID. The optional 'website' is described only in the schema and is not addressed in the description, so nothing compensates for the coverage 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 names a specific resource and aim: the facts needed to write an opening line for one company, enumerated concretely (trial, hire, FDA decision, funding, news) plus rep-fit signals. It also draws a boundary that separates it from line-generating tools ('Returns the facts, not the lines'), though it never names a sibling such as company or news directly.

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 by the enumeration of fact categories; there is no explicit statement of when to call this versus siblings like company, account, news, or find, nor any prerequisites or exclusions. An agent can infer the intent but must guess at the routing decision.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description adds genuine value by disclosing the response payload (companies in rank order, each with fit, why-now and source, plus uncovered names). It omits one behaviorally significant fact for a partial-name lookup: what happens when the fragment matches multiple sets or none.

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?

It is one sentence with no filler, but it is a grammatically incomplete fragment that strings together three loosely joined ideas with 'and ... and.' The trailing clause 'the names Whimbrel does not cover' is cryptic internal jargon that costs the reader effort rather than saving it.

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

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

With no output schema, the description must carry return-value semantics and it partly does, describing the shape of each company entry. But for a lookup tool with two optional-and-unconstrained parameters (no required fields) it should say what happens on zero or multiple matches, and 'Whimbrel' is never explained. Adequate, but a meaningful behavioral gap remains.

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 fully documented, and the description largely restates them ('by its name (or part of it) or id'). It adds the hint that id and name are alternative selectors, but gives no tie-breaking or format guidance beyond the schema. Baseline 3 applies when 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 identifies the resource precisely — a single saved ranked set, looked up by name (full or partial) or id — and distinguishes it implicitly from list_ranked_sets (one vs. many) and from rank_list (it returns the set 'as rank_list returned them,' i.e. a stored snapshot rather than a fresh computation). It lacks an explicit verb, opening with the bare noun phrase 'One saved ranked set,' so the action (open/retrieve) is only inferable from the name and title.

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 statement of when to use this versus the obvious siblings: list_ranked_sets (to discover what exists) or rank_list (to compute a ranking). The reader must infer that a prior list_ranked_sets call supplies the id, and the description never says this tool should be preferred when the set already exists. No exclusions, no prerequisites, no error-path 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 declare non-read-only, non-destructive, idempotent, closed-world, and the description goes well beyond them: it scopes the blast radius ('only hides that company for this rep', 'never changes the firm profile', 'does not move any other company') and discloses a non-obvious branch — an unclear name yields a say_now requesting the website rather than an error. With no output schema, that return-behavior detail is exactly the missing context.

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

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

Front-loaded with the action and the strongest disambiguation ('not a fit'), then alternatives, then a closing response directive. Dense but nearly every clause carries information; the final formatting instruction ('Say what was passed in one line') is mildly procedural but still earns a slot as output guidance absent 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?

For a two-parameter, non-destructive hide action with no output schema, the description supplies scope, side-effect boundaries, the inverse operation, and what happens on ambiguous input — everything needed to invoke it correctly and explain the result to a rep.

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 (company, website) are already documented as fully as the schema allows, which sets the baseline at 3. The description only lightly touches parameter meaning — the website is implied as a conditional follow-up when a name is unclear — but adds no syntax, format, or disambiguation rules for the company string.

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 — 'Hides one company from the rep's suggestions' — with a concrete example ('pass on Acme'). It also explicitly separates itself from the nearest confusable concept ('it is not "not a fit"') and from its sibling restore_company, so an agent can distinguish it 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 an explicit when (use Pass rather than 'not a fit'), names the inverse tool restore_company and its condition ('brings it back'), and specifies the fallback path when the name is unclear (a say_now asking for the website). That is when-to-use, when-not-to-use, and the alternative all in one place.

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

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

Goes well beyond the annotations: discloses that work emails are looked up externally for top names, that records older than a week are returned as stored with a refresh offer, and that a new record consumes one monthly record and takes ~5 minutes. This coherently explains readOnlyHint=false without contradicting any hint, though the interaction pattern with the rep could be stated slightly more compactly.

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 user-facing trigger before any mechanics, and nearly every sentence carries operative information (roles, record gating, cost, timing). It is long and occasionally convoluted ('The people Whimbrel's full company research names at one company, by role'), which keeps it out of the top band.

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 enumerating return contents, including the fallback path (SBIR, registry, ClinicalTrials.gov contacts) and the company's published contact routes. Cost, latency, staleness handling, and consent gating are all covered, so an agent has everything needed 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 80%, so the baseline is 3, but the description adds real meaning: role filters only researched people (not government-record names), start_new_record is gated on explicit rep consent, and domain is a retry signal to ask the rep for a website on uncovered companies. That is more than the schema alone conveys.

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 resource (named people at one company) plus concrete return content: title, source, date, LinkedIn people search, published email/phone, and company contact routes. The trigger phrasing ('who to contact at a company', 'who runs quality at X') is specific enough to separate it from generic siblings like company or account.

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

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

Opens with an explicit when-to-use trigger, then gives a when-not-to: it will not start a record on its own and instead lists government-record names and asks first. It also names the condition for the alternative path ('Pass start_new_record true only after the rep says yes') and cites the cost of a fresh lookup.

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 only mark this as a non-read-only, non-destructive, non-idempotent call; the description adds the crucial conditional side effect (a name saves the set under Rankings, no name saves nothing) plus the shape of the result, including uncovered names returned separately with reasons. That is real context the annotations cannot convey.

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

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

The purpose is front-loaded, but the prose is chatty, with parenthetical examples and a repeated restatement of the save-versus-no-save behavior that could be one clause. Each sentence carries information, yet the phrasing is longer than needed.

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, and the description compensates by enumerating the returned fields (position, fit, why now, newest evidence with sources, rep status) and the handling of uncovered names. An agent knows what it will get back and what side effect occurs.

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 a 3 would be the floor, but the description goes further by explaining that 'name' is what triggers persistence and ties it to the app's Rankings view. It adds no detail on the 60-name cap since the schema already states 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 states a concrete verb and resource (orders a pasted list of company names) and describes what the ordering consists of. It implicitly separates itself from list_ranked_sets/open_ranked_set by explaining that ranking produces a set that may then be saved, but it never names a sibling as the alternative.

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 triggering context (a rep pasted a territory, exhibitor list, or target list) and spells out the branch between passing a name versus omitting one. It stops short of saying when to use list_ranked_sets/open_ranked_set instead or what happens on resubmission.

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 behavior beyond the annotations: add/update only, nothing is ever deleted, "we only do X" replaces rather than appends to a field, and excluded companies stay out of new results. It also discloses the return shape (a short confirmation plus changed/change_id) and links change_id to undo_change, which matters since there is no output schema. Consistent with destructiveHint=false and idempotentHint=true.

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 and the trailing sentences each carry weight (replacement semantics, return value, undo link). However, the first sentence is a long comma-spliced enumeration of fact categories that could be tightened without losing 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?

Covers everything needed for a memory-write tool with only two parameters and no output schema: when to call, what to pass verbatim, how pronouns are resolved, how field replacement works, what comes back, and how to reverse it via undo_change.

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 already 100%, yet the description still adds real meaning: pass the rep's words verbatim and in full, and supply companies currently on screen, in order, so pronouns like "them" and "the second one" resolve. That is usage semantics the schema's terse field descriptions do 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?

Opens with a specific verb+resource ("sharpens the rep's firm profile") plus the payoff ("so Whimbrel surfaces more relevant medical device companies"), then enumerates exactly what kinds of facts it captures. It is clearly distinguishable from the sibling forget, which it names 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?

Gives an explicit trigger: "Call it the moment the rep says remember, keep, note or save this about their firm, and for what they mention in passing." It also states the exclusion path — a forget request returns to_forget and deletes nothing — so the agent knows which sibling takes that case.

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 and idempotentHint=true, so the mutation profile is known. The description adds real value beyond them: removal propagates to the app UI ('in the app too') and a company watch survives the removal unless separately stopped. It does not mention confirmation or whether targets can be re-added, but the side-effect disclosure is solid.

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 action and its example, followed by the two disambiguating facts. Nothing is redundant with the title or restates 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?

For a one-parameter destructive tool with rich annotations and no output schema, the description covers the essential behavioral nuance an agent needs before calling it. A note on whether reminders or confirmations occur would make it fully complete, but no critical gap remains.

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 'Company names, up to 50.' The description only reinforces this implicitly through the Abiomed example, adding no new constraints or format detail beyond the schema, 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?

Names a specific verb and resource (removes companies from the rep's targets) and anchors it with a natural-language example ('take Abiomed off my targets'). It also distinguishes the action from two neighbors in the sibling list: unwatch ('a watch stays') and a not-a-fit marking ('removing is not marking a company not a fit').

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 example phrasing makes the triggering intent clear, and the last two sentences act as exclusions by ruling out adjacent operations (stopping a watch, marking not a fit). It never explicitly names alternative tools such as unwatch or add_target, so the routing is implied rather than stated.

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

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

Beyond the read-only annotations, the description discloses important behavior: request_id triggers a wait of up to 45 seconds, long-running requests must be polled manually until done or failed, results should not be handed directly to the user, team accounts include seats claimed, and an active Whimbrel plan is required.

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: it opens with the resource and status categories, then covers parameter usage, polling behavior, team-account output, and prerequisites. Every sentence contributes 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?

For a read-only status tool with no output schema and a single optional parameter, the description covers the main operational questions: what is returned in aggregate, how request_id changes behavior, waiting/polling rules, and plan requirements. It could say more about the return shape, but it is otherwise complete enough 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?

Schema coverage is 100%, so the parameter is already documented. The description still adds meaningful semantics by explaining that request_id selects one request and omission returns the recent ten, and that request_id changes the waiting behavior.

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 status resource and enumerates exactly which records are included: queued, running, and finished new company records, onboarding requests, records left this month, and saved watches. This is far more specific than a generic status tool and lets an agent distinguish it from sibling tools such as check_space_watch or account.

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 explains how to use the parameter: pass request_id for one request or omit it for the recent ten. It also gives polling guidance for long runs and notes the active-plan prerequisite, but it does not explicitly name alternative tools or when-not-to-use cases.

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 cover the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the description is correctly lower-burden here. It still adds genuinely non-obvious behavior: calling with no company silently becomes a read/list operation returning the passed-on companies newest-first. It doesn't say what happens if the company was never passed on or the name is ambiguous.

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, both load-bearing, with the primary restore action stated first and the no-argument fallback second. No filler or 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?

There is no output schema, so the description must carry return behavior – and it does for the empty-argument path. It leaves the restore path's outcome (confirmation payload, error on unknown/ambiguous company) unstated, which is the one gap for a state-changing 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 a single parameter at 100% schema description coverage, the schema already explains that the value identifies the company to restore and that empty means list – the description repeats rather than extends it. The only added semantic is the 'newest first' ordering on the empty case, which is return behavior, not parameter 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?

States a specific verb and resource: it moves a company the rep passed on back into their suggestions. The second sentence clarifies the second mode (no argument). It's clearly distinguishable from pass_company, though it never names that sibling 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?

"Brings a company the rep passed on back into their suggestions" gives a concrete when-to-use condition, and "Leave empty to see what was passed on" routes the discovery case. No explicit when-not or named alternative tool (e.g., pass_company to reverse this) is 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?

The description adds substantial behavior beyond the annotations: it returns must-see and worth-a-stop booths with fit rationale, change notes, and sources; excludes clients and non-fit companies; saves nothing; and explicitly says Whimbrel does not hold any show's exhibitor list. This is unusually complete for an agent deciding whether and how to call it.

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 ranking action and return categories, and every sentence carries relevant instructions or constraints. It is somewhat long but mostly earns its length through operational detail.

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

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

With no output schema, the description still explains the return structure (must-see vs. worth-a-stop booths with reasons, changes, and sources), the exclusion behavior, the no-save behavior, and the fallback when no exhibitor list exists. It is complete enough 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?

Schema coverage is 100%, so the schema already documents exhibitors and show. The description still adds useful semantics: exhibitors may come from pasted, uploaded, or directory-read names, and lists over 200 should be split across multiple calls.

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: it ranks a trade show's exhibitor list for the rep's firm and returns must-see booths with reasons. It does not mention the sibling tool rank_list, 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?

It gives clear operational guidance: pass exhibitor names the rep pasted, uploaded, or read from the directory, and split lists longer than 200 names across calls. It also tells the agent what to do when no exhibitor list is available, though it does not compare itself directly to alternatives like rank_list.

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 the genuinely useful clarification that targets are untouched, preventing confusion with remove_target. It falls short of saying whether the stopped watch is deleted or merely deactivated, and whether it can be resumed.

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

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

Two sentences, zero filler, with the action and scope front-loaded and the identifier sourcing plus the exclusionary note following in priority order. Nothing needs trimming.

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, idempotent mutation with no output schema, the definition covers what to pass and that targets are unaffected, but omits what actually happens to the watch object (deleted vs. paused), whether reinstatement is possible, and what a successful call returns. These are real gaps for an agent that may need to warn a user before acting.

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% (only `name` is documented), so the description must compensate and it partly does by naming all three input forms and framing them as alternative identifiers. However, it never says that exactly one of company/name/watch_id is expected, says nothing about watch_id format, and leaves `company` completely 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?

"Stops watching a company or a space for the rep" pairs a specific verb with the exact resource and scope, and the parenthetical example ("stop watching Abiomed") removes ambiguity. An agent can distinguish this from watch_company, save_space_watch, and remove_target 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?

It explicitly tells the agent where to get the identifier ("the watch's name or watch_id from list_watches"), which routes to the correct sibling for discovery. It also implicitly demarcates itself from remove_target via "Targets are not changed," but never states when one would stop a watch versus delete it, nor any prerequisite/permission context.

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 it is a non-destructive, idempotent mutation (readOnlyHint=false, idempotentHint=true). The description adds useful behavior beyond that: it returns the company's latest change and, on an unclear name, returns say_now prompting for a website. It could have said more about permissions or error cases, but the annotation coverage lowers the burden.

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 core action and example. Each sentence adds distinct information: what it does, how it differs from add_target, and what happens on ambiguity.

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 two parameters, the description covers the action, the sibling exclusion, the return value ('latest change'), and the ambiguity fallback. Minor gap: the say_now tool is not listed among siblings, so the fallback reference is slightly under-contextualized.

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 documents both parameters. The description adds value by explaining when the optional website parameter is used ('when a reply asked for it') and by connecting an unclear company name to a say_now response requesting the website.

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 ('Starts watching one company'), gives a concrete example ('watch Abiomed'), and explicitly distinguishes this from add_target: 'adding a target does not watch it.' The sibling tool names confirm this differentiation matters.

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 'This is the only way a company watch is made; adding a target does not watch it,' routing the agent away from add_target. It also tells the agent the fallback path when the name is unclear: returns say_now asking for the website.

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 and readOnlyHint=false; the description adds the key operational detail that re-watching the same name replaces the existing search, which is exactly the kind of consequence an agent needs. It also describes what comes back (total match count and the top-ranked match) despite there being no output schema. It stops short of saying whether a replaced watch loses its history or what authorization is needed.

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 content is dense and front-loaded with the verb, but it is delivered as one long run-on sentence with awkward embedded asides ('for the rep ("watch neuromodulation in Minnesota"), their own'). It is information-dense rather than padded, yet the structure makes it harder to parse than it needs to be.

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

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

For a mutating, destructive-hinted tool with six optional parameters and no output schema, the description covers the replacement semantics, the return shape, and the follow-up tool (check_watches). Missing pieces are minor: whether a replaced watch resets its state and how this relates to unwatch/watch_company.

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 goes beyond the schema by explaining that these fields compose a find search: the name is the label, while about (device/technology/space) or role (a role being hired) are the subject, refined by stage, state, and evidence kinds. That compositional relationship is not stated anywhere in 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?

The description states a specific verb and resource (watch a space) and maps it onto the user-visible concept ('the same space the Whimbrel app shows under Watches'), plus a concrete example ('watch neuromodulation in Minnesota'). It does not differentiate from the sibling watch_company or add_target, which is the only thing keeping it from a 5.

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 through the framing ('a find search under a name...') and it does route to check_watches for what is new, plus discloses that re-watching the same name replaces the search. However, there is no explicit statement of when to use this versus watch_company, add_target, or unwatch, so the agent must infer the boundary.

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