Whimbrel MedTech Analyst

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?

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=true; the description reinforces this with 'nothing is deleted' and the recoverability detail that earlier answers can be restored from the Memory page. It also discloses side effects the annotations don't imply — that passing a website causes the site to be read and a profile drafted, and that set_up_now is returned until the profile exists. Missing only rate/limit or failure-mode detail.

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 paragraph is packed but front-loaded on a weak, abstract headline, and several sentences are run-ons that mix three distinct modes (build flow, field update, read). It introduces response-side names like ask_now, say_now and set_up_now without a clear frame, forcing re-reading. Little is wasted, but the structure does not help an agent parse the modes quickly.

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 16 parameters and no output schema, the description does take on return-shape duty (profile, best-fit audience, seats, billing/invites page, data provenance, Memory page, next question, set_up_now), which is genuinely helpful. But it leaves roughly half the input surface (role, notes, proof, firm_name, certifications, device_classes) with neither schema nor prose explanation, so an agent still cannot confidently populate the full schema.

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 56%, so both the schema and the description carry weight. The description adds real semantics for step and skip that the schema cannot express (skip is only meaningful paired with step, and step carries the ask_now.step value), and names several update fields (services, device_areas, customer_stage, territory, clients, skip_companies, accounts). Fields like role, notes, proof, firm_name, certifications and device_classes remain unexplained in either place.

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 headline 'The rep's own setup in one place' is vague, but the body does state concrete behaviors: it starts the profile build, returns the next question one at a time, accepts any profile field for update, and with no arguments returns the profile, seats, billing page, and data-source info. The tool is really a read-or-configure entry point for the rep's profile, and an agent can infer that only after reading the whole paragraph. It never contrasts itself with siblings like company, people, or about_the_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?

Usage is implied through modes rather than stated as guidance: 'On first use it starts the profile build', 'Pass each answer with step ... or step with skip true', and 'With nothing passed' enumerates the read mode. That covers the main invocation patterns but gives no explicit when-to-use-this-vs-another-tool routing, and no prerequisites for starting the build flow.

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 readOnlyHint=false and idempotentHint=false, and the description corroborates and enriches this by disclosing the actual side effect: it 'marks it as seen so the next check starts from now', which explains why repeated calls yield different results. This is meaningful behavioral context beyond the annotations, though permission/rate-limit behavior is unaddressed.

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 a single dense sentence, but it is front-loaded with the core action ('Runs a saved watch's find search again') and every clause carries information. The run-on length is the only minor cost to readability.

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

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

With no output schema, the description takes on the return-value burden and does so reasonably: it specifies device companies plus only-new evidence and its source, and explains the since-last-checked window. It could still clarify behavior on an unknown name or empty results, but the essential contract is covered.

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

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

Schema description coverage is 100% with a single parameter, so the schema already documents 'name'. The description only loosely ties it to a 'saved watch's find search' and adds no syntax, format, or validation 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?

States a specific verb and resource: re-runs a saved watch's find search and returns newly surfaced device companies with evidence. An agent can distinguish this from save_space_watch (creation) and find (ad-hoc search) without opening a schema. It stops short of naming those siblings explicitly, so it is clear but not fully differentiated.

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 'Runs a saved watch's find search again' and 'since it was saved or last checked', which signals the tool operates on an existing watch. There is no explicit when-to-use vs an alternative, and no exclusions or prerequisites (e.g., what happens if the watch name doesn't exist).

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, idempotent, non-destructive, closed-world). The description adds value beyond that by disclosing the off-list behavior (it will say a company isn't on the list and why) and the structure of returned data. It doesn't discuss pagination or auth needs, so not a full 5.

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

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

Front-loaded with the core purpose, then a long but purposeful enumeration of return contents and the trigger phrasing. The event-list enumeration is dense, but each clause maps to real content the tool surfaces.

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

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

No output schema exists, so the description must carry the return-value burden, and it does thoroughly by listing every category returned and noting dates and source links. Combined with annotations covering safety, 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 description coverage is 100%, so the schema already documents both params, including the events default/limit and the "as the rep said it" framing. The description adds no syntax or format detail beyond the schema, making the baseline 3 correct.

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 ("rundown on one company") and enumerates exactly what it returns: list membership and reason, what it makes, stage, location, FDA facilities, and all filed events with dates and source links. An agent can immediately tell this is the company-level profile tool, distinct from list/set tools like find or rank_list.

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

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

Gives explicit trigger phrasing ("Use it for 'tell me about' or 'what do we know about' a company") and clarifies the negative case ("A company not on the list says so, so the rep does not pitch a foreign importer or a drug company"). It does not name a sibling alternative, but the context is clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive safety, so the bar is lower; the description adds real value by disclosing the return composition (CSV files, sourced research-notes document, CRM import steps) and the auth/record prerequisites. It omits any detail on file count, size, or failure modes if the record is missing.

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 what is produced, then parameters, then prerequisites. No redundant or filler text.

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, no output schema, and annotations covering safety, the description covers purpose, inputs, return artifacts, and prerequisite conditions. Nothing material an agent needs 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% with both parameters documented and format's enum spelled out, so the description repeating 'pass company and format (hubspot or salesforce)' adds no syntax or constraint 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 (export) and resource (one company's deep-research record) plus the output form (CRM import files), which distinguishes it from siblings like deep_record and research_status. An agent can tell exactly 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 states prerequisites: an existing deep-research record and an active Whimbrel key, and points to the format choice. It does not name an alternative tool or say when not to use it, so it falls short of full routing 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?

Beyond the annotations it discloses the key behavioral traits: this is not a pure read (it queues an external research run), the staleness policy (records under a week are served as stored, older ones refresh automatically), that `fact` short-circuits the run, that a partial result is returned with a note on what is still filling, and that an active Whimbrel key is required. That is substantive cost/auth/side-effect context the annotations alone would not 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?

Purpose and output shape are front-loaded, and the policy details follow in a logical order. The run of short 'Pass X' sentences mirrors the schema rather than adding to it and costs a little density, but nothing is truly wasted.

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: it enumerates the record's sections and explains the partial-with-note case. Auth and refresh semantics are covered; the only real gaps are the undocumented `since` parameter and no sense of run latency.

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%, so 3 is the floor; the description goes slightly beyond by tying `domain` to the 'new company not on the list' case, tying `refresh` to overriding the auto-refresh rule, and clarifying that `fact` returns stored data without queueing. It omits `since` entirely, so it does not fully supersede 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?

It clearly states the resource: a full research record on one company (company facts, named partners, dated events, evidence, gaps), plus the side effect of queueing a run when stale or missing. An agent can tell it apart from a lightweight lookup, though it never names the sibling (`company`, `research_status`) that would be the obvious alternative for a plain lookup or a status check.

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 real selection cues: use it 'when the rep asks for one', pass `fact` to get a single stored fact 'without queueing a run', pass `refresh` to force a new run, and it explains the automatic refresh threshold (>1 week). What is missing is an explicit 'when not to use this / use X instead' against the many sibling tools.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds real behavioral depth: it names the data sources (trials, FDA device makers, filings and news, hiring), states the aggregation ('one row per company with its evidence and sources'), discloses exclusions (rep's clients and non-fit companies), and explains the ranking basis. It stops short of freshness, latency or auth details, but this is well beyond what the annotations 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?

Purpose is front-loaded in the first sentence, but the body is padded and circular, repeating 'a device, technology or space' three times and re-listing the filter dimensions already given up front. Several clauses could be cut 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?

With no output schema, 7 optional parameters and a rich annotation set, the description does the necessary work: it covers input modes, evidence sources, filtering, ranking and the empty-query fallback, and sketches the result shape. It is close to complete for an agent to call it correctly, missing only output-field specifics.

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 parameter is already documented, and the description largely restates them ('a role being hired, a US state or a date'). The one added nuance is that `about` is free-form plain words and that a vague ask routes to firm-ranked results, but no syntax or format detail is added 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 ('Finds US medical device companies') plus the filter dimensions, and explicitly scopes the output shape ('answered as companies') which separates it from the people/news siblings. An agent can tell it is the umbrella company-search tool without opening a schema.

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

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

It gives an implied usage pattern and one explicit scenario ('With no device or role named... it leads with the companies Whimbrel ranks first'), which tells the agent the tool works with zero arguments. However, it never names an alternative or a when-not condition (e.g. use `company` for a known company, `people` for people), so the routing guidance stays 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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the description's job is to say what destruction means — and it does: status is cleared, entries are removed from named firm-profile lists, while 'the companies and their public records are not affected.' It also points to the Memory page for the rest of the profile, which is real routing context. It does not say what happens when a listed company isn't present, or whether the action is confirmed/undoable.

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 verb and what is destroyed, then the mode split, then the non-effects. One dense paragraph with no filler, though the nested parentheticals (status, then three list names) make it slightly harder to parse than a bulleted split would 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 two-optional-parameter destructive tool with no output schema, the description covers the essential unknowns: what is deleted, what is untouched, and which surfaces are affected. Remaining gaps are small — whether both arrays can be supplied together and what the response reports — but nothing that would cause a wrong 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 baseline is 3, but the description adds genuine meaning: `companies` is described as writing status (client / not a fit) and removing from three specific lists, while `stop_working` is scoped to the prospect list only — a distinction the terse schema descriptions ('profile entries' vs 'the rep's accounts') leave ambiguous.

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 ('Deletes what Whimbrel keeps for this rep about a company') and immediately splits it into the two distinct modes the schema exposes (companies vs stop_working). It does not explicitly contrast with the inverse sibling `remember`, so it stops 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?

Provides a clear trigger ('when the rep asks') and, more usefully, states the selection rule between the two parameters: `companies` clears status and profile lists, `stop_working` only removes from the prospect list. It never says when to prefer another tool, such as re-adding a company via `remember`, so exclusions are absent.

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 declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false; the description adds real behavioral context the annotations cannot convey. It discloses that links open a one-month trial that then converts to paid, that no API key is required, that a quantity under 5 is refused, and the post-call workflow (collect the key from the success page and send it as an Authorization Bearer header).

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 return value is front-loaded and most sentences carry operational weight (plan options, refusal threshold, OAuth alternative, how to use the link). There is mild sprawl in the final two sentences and the OAuth aside is slightly tangential for a tool whose job is returning links.

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

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

With no output schema, the description carries the burden of explaining what comes back, and it does so (Stripe Checkout links per plan). It also covers auth expectations on both paths, so an agent knows nothing needs to be passed and what to do with the returned link. Only edge details, such as whether quantity is meaningful when plan=individual, are left implicit.

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 already states 'Omit to open both' for plan and 'Below 5 is refused' for quantity, so the description largely repeats what the schema provides. It adds only the minor mapping that 'seat' means five or more people, which does not materially extend meaning beyond the structured fields.

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 concrete verb and resource: 'Returns Stripe Checkout links for Individual and Team,' which is unambiguous and matches the get_access title. It does not reference any sibling tool, though none of the listed siblings (account, my_contacts, etc.) overlap with billing, so the risk of mis-selection is low.

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 selection condition explicitly: 'These links are the display-key path for clients that do not use OAuth,' and contrasts that with the OAuth Subscribe path that needs nothing pasted. It also states the plan/omit semantics and the quantity-below-5 refusal. What is missing is only an explicit 'use this instead of X' phrasing against 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is context, and it delivers: the result is 'one row per company with dates and source links, ranked for the rep's firm', and coverage is limited to 'the last days' of US-sourced events. It does not discuss pagination or what happens if no events are found, but the aggregation/ranking behavior is genuinely 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?

The purpose is front-loaded in the first clause and the rest is a single dense paragraph. Five inline example questions are a lot of surface area, but each one demonstrates a distinct query shape (recall, clearance, space, timeframe), so they earn most of their space.

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 burden of describing the return, and it does: row-per-company granularity, dates, source links, and ranking. Scope (US only, device companies and suppliers) and recency window are stated. Missing only edge-case behavior such as empty results or how 'ask' interacts with 'about' when both are supplied.

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

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

Schema description coverage is 100%, so the five parameters (ask, days, about, limit, state) are already fully documented including defaults and maximums. The description adds only indirect meaning — 'last days' gestures at the days window and 'one row per company' gestures at limit — without restating or enriching parameter semantics. 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?

The description names a specific resource (US medtech news events at medical device companies and their suppliers) and enumerates the event types covered: FDA clearances, recalls, warning letters, trials, funding, press releases, hiring. An agent can tell this is a news-feed tool, but it never explicitly contrasts itself with near-neighbors like 'today' or 'company', so sibling differentiation is only implicit.

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

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

Five concrete example questions ('any news in medtech', 'what's new this week', 'anything new in neuromodulation', 'who got FDA clearance lately', 'any recalls') make the triggering intent very clear. However, it gives no when-not guidance and never names an alternative tool, so an agent must infer the boundary against 'today' or 'deep_record' on its own.

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

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

Annotations already cover the safe read-only profile, and the description adds useful behavior detail: it aggregates company events with sources plus rep-profile matches and fit information, and it explicitly returns facts rather than generated lines. It does not describe output format or pagination, but the key behavioral distinction is present.

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

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

The purpose is front-loaded and the wording is dense but efficient, covering multiple returned fact types without filler. The middle clause is lengthy and list-heavy, but every part contributes to understanding what the tool returns.

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 simple one-parameter tool with no output schema, the description does a good job enumerating what is returned, including sources and rep-fit context. However, it leaves a critical invocation detail ambiguous: what exactly the 'company' input should contain.

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 description coverage for the single required 'company' parameter. The description only says 'one company' and gives no indication of whether the value should be a name, domain, ID, or another identifier, so it does not compensate for the schema 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 gives a specific verb-and-resource picture: it fetches facts used to write an opening line for one company, and it enumerates the kinds of facts returned. It clearly distinguishes itself from line-generation by stating 'Returns the facts, not the lines,' though it does not name sibling tools.

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

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

The usage context is clear: use it when you need supporting facts for an opening line about a single company, not when you need the line itself. There are no explicit exclusions or named alternatives, but the context is strong enough to guide selection.

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

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

Beyond the annotations, the description discloses important behavior: it may trigger a full company research job, returns interim government-record contacts unsorted by role, provides a request id for the eventual full list, and performs work-email lookups for top names. This is consistent with readOnlyHint=false and gives the agent real operational context.

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

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

The purpose and behavior are front-loaded, but the full role list largely duplicates the enum descriptions in the schema, making the description longer than necessary. The fallback behavior is dense but 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 does a good job explaining the return shape, the interim government-record fallback, timing, and contact routes. It could mention limit behavior or how to use the request id with research_status, but it is 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 75%, and the description adds meaningful semantics for the role parameter by spelling out the role groups, and for domain by explaining when to ask the rep and retry. It does not add much for limit or company, but the schema covers those adequately.

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 lists the people named at one company, grouped by role, and specifies the returned fields (title, source, date, LinkedIn search, contact details). This is clearly distinguishable from the broader sibling 'company' tool.

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 explains the key usage scenario: when no research from the last week is on file, the call kicks off full company research and returns preliminary government-record names with a request id. It also instructs the agent to ask the rep for a domain when prompted. It does not explicitly compare against siblings like 'company' or 'find', but the context 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 read-only, idempotent, non-destructive behavior, and the description adds genuine context on top: the response structure (position, fit, why now, newest evidence with sources, rep status) and how unmatched names are handled ('come back apart, with why'). 'Saves nothing' reinforces the no-side-effect contract. It stops short of stating latency, rate limits, or auth needs.

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

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

Three sentences, front-loaded with the core operation, and each sentence adds content (input framing, return contents, unmatched handling). Slightly dense with parenthetical asides ('a client, or not a fit'), but nothing is truly wasted.

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

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

With no output schema, the description carries the burden of explaining return values and does so in detail, and it clarifies the non-persistence behavior for a stateful-sounding tool. Given the trivial one-parameter input and existing annotations, this is close to complete; only routing guidance versus siblings 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?

There is a single parameter and schema description coverage is 100% ('The company names to rank, at most 60'), so the schema already carries the semantics. The description's mention of pasted lists adds framing but no syntax or format detail beyond what the schema provides, 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 (orders/ranks) and resource (a pasted list of company names), and enumerates the paste contexts (territory, exhibitor list, target list). This is clear, but it never contrasts itself against siblings like 'company', 'find', or 'deep_record', so the agent must infer when ranking beats a lookup.

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 framing ('a list of company names the rep pasted'), which tells the agent this is a batch-ranking call rather than a single-company lookup. However, there is no explicit when-to-use/when-not guidance and no named alternative for the single-company 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?

Beyond the annotations (idempotentHint, destructiveHint=false), the description discloses that it only adds and updates, that a forget request deletes nothing and returns to_forget and the named companies, that clients and non-fits are excluded from new results, and that it returns a short confirmation. That is substantial behavioral context an agent cannot get from the annotations alone.

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 scoping and mutation-safety information is front-loaded and every clause carries meaning, but the middle section is a long run of comma-separated examples that makes it slightly dense. Efficient overall, with minor rambling.

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, mutation-flagged tool with no output schema, the description covers the write scope, the refusal/deletion behavior, the effect on future results, and the return format ('a few words saying what was kept'). 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 coverage is 100%, so both parameters are already documented, including companies_on_screen's ordering for 'them'/'the second one'. The description reinforces the purpose of companies_on_screen for pronoun resolution but adds no syntax or format detail beyond the schema. 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 description names a specific verb and resource ('Sharpens the rep's firm profile from what they say in passing') and enumerates the categories of facts it captures, so the agent knows it is a profile-update tool rather than a search tool. It distinguishes itself from the sibling 'forget' by explaining what happens on a forget request. Slightly indirect phrasing ('sharpens... from what they say in passing') keeps it from a crisp 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?

It spells out when to use it – to record what the firm sells, device strengths, stage, geography, clients, or non-fits – and explicitly redirects a forget request to 'to_forget' behavior, so the boundary against the sibling 'forget' is clear. It stops short of stating exclusions for unrelated utterances or other alternatives.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower, yet the description adds real context: an active Whimbrel key is required, the default response is capped at ten requests, and Team-plan replies include seats claimed. It does not, however, describe rate limits or the shape of the payload returned.

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, zero padding: purpose first, then invocation, then plan/auth caveats. Every sentence carries information and there is no 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?

With no output schema, the description does the work of indicating what comes back (statuses across queued/running/finished, plus seats claimed on Team plans) and what is required to call it. It is nearly complete for a simple single-param read tool; only the exact response fields and id provenance remain 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 description coverage is 100% and the single optional request_id is already documented in the schema, so the baseline is 3. The description restates the one-vs-ten behavior consistent with the schema but adds no format details (e.g., where the id comes from, accepted id form).

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

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

States a concrete verb+resource: retrieving status for queued, running, and finished research/onboarding requests on this account. The scope is unambiguous (this account, three lifecycle states). It does not name or contrast with any sibling, though none of the siblings listed (find, remember, account, etc.) appear to overlap, so differentiation is largely implicit from the name.

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 tells you how to invoke it (pass request_id for one, omit for the recent ten) but says nothing about when this tool is the right choice versus another (e.g., find or deep_record for related research data). Usage is implied by the resource description rather than explicitly guided, and there are no stated exclusions.

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

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

Annotations declare destructiveHint=true and idempotentHint=false; the description is consistent, disclosing that 'Saving the same name again replaces the search' and that the write is scoped to the calling account. It could be more explicit that the prior watch is overwritten/lost, but it adds real behavioral context (ranked result set, later reply behavior) on top of the annotations.

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

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

The core action and replacement semantics are front-loaded, and sentences are dense with no filler. The trailing sentence about later replies and check_space_watch is slightly tangential to invoking this tool but earns its place by explaining the watch lifecycle.

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 no output schema, the description covers all the key concerns: account scoping, overwrite behavior on duplicate name, and what the immediate response contains (matching device companies, ranked as find ranks them). It is complete enough to call correctly.

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

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

Schema coverage is 100%, so the schema already documents all five parameters and their examples. The prose largely restates those fields ('a device, technology or space (about) or a role being hired (role)'), adding only minor relational framing between about/role, so the 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: 'Saves a find search under a name, for the calling account only.' It also names the two modes (about / role) and the retrieval sibling check_space_watch, so an agent can distinguish it from check_space_watch 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 gives clear context for when this is used (to persist a search that later surfaces new evidence) and routes the agent to check_space_watch for retrieval. It does not state exclusions, e.g. when to prefer find or remember instead, 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 declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real value beyond them: 'Saves nothing' confirms no persistence, and the 200-name-per-call limit is a concrete batching constraint an agent must respect to avoid failures.

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 and inputs are front-loaded, and the operational constraints (no saving, 200-name limit) are placed last where they belong. Mostly tight, though 'Whimbrel checks each name against the archive' is mildly redundant with the ranking claim.

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 burden and does: must-see booths plus worth-a-stop ones, each with fit rationale, what changed, and sources. Exclusions and side effects are also stated, so an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so baseline is 3. The description goes further by explaining what the exhibitors array actually contains and where those strings originate (pasted, uploaded, or read from a directory), and ties the 200-item limit to that parameter, which the schema does not.

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 — ranks a trade show's exhibitor list — and adds the scoping that matters: it is ranked for the rep's firm and clients/non-fits are excluded. An agent can tell this apart from generic siblings like rank_list or company 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?

Clearly says where the input comes from (names the rep pasted/uploaded, or names read off the show's exhibitor directory) and gives an operational constraint: lists over 200 names must be split across calls. It stops short of naming a specific alternative tool or a when-not-to-use condition.

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