Debriefing

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

Annotations already declare readOnly=false, destructive=false, and idempotent=false. Beyond that, the description adds genuine behavioral context: the saved note is treated as framing for the next battlecard rewrite and is explicitly never consumed as a verified fact, which materially affects how an agent should phrase content. It stops short of stating auth requirements or what the note does if a battlecard is regenerated.

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 tightly packed sentences with no filler, and the purpose is front-loaded. The prose leans metaphorical ("no page says") rather than plain, which costs a bit of immediate comprehension but not length.

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 an output schema present and annotations covering the safety profile, the description need not explain return values or side-effect safety, and it usefully covers consumption semantics. However, for a tool with four near-duplicate note-adding siblings, the absence of any routing guidance leaves a real gap for correct tool selection.

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%: body's length bounds and plain-text nature and competitor_id's origin from list_competitors are all documented in the schema. The description adds no format, syntax, or sourcing detail beyond that, 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 description conveys a write action tied to competitor battlecards ("Adds what the team knows about a core competitor", "the next rewrite of its battlecard"), but it is phrased metaphorically and never plainly says it attaches a note to a battlecard's record. It also does nothing to separate itself from sibling note-writing tools like add_signal_note and add_digest_note.

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 a faint hint about the kind of content this accepts ("what the team knows... that no page says"), but no explicit when-to-use, no prerequisites, and no mention of the alternatives such as add_signal_note or add_digest_note despite several near-identical siblings.

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 the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false). The description adds value beyond them: an admin permission requirement, a plan quota constraint with a pointer to the limits tool, and the fact that monitoring begins automatically. It does not mention duplicate-handling despite idempotentHint=false.

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 core action, then permissions, then quota. Every sentence carries a distinct piece of information with no padding.

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?

An output schema exists, so return values need no explanation, and the description covers auth, quota, and the downstream monitoring effect. The one visible gap is behavior on duplicate adds, which matters given the non-idempotent annotation.

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

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

Only one parameter and schema description coverage is 100%, so the schema already documents website_url fully. The phrase 'from its website' slightly reinforces that the URL identifies the competitor, but adds no format or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Adds a competitor to the workspace's core watchlist from its website') plus the downstream consequence ('Debriefing then monitors it'). This clearly separates it from siblings like add_monitored_page, research_competitor, and refresh_watchlist.

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 precondition ('Admin only') and routes the agent to get_plan_and_limits for free slots, which is real conditional guidance. It does not, however, state when a competitor should be researched instead of added, so the alternative-selection story is incomplete.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true. The description adds one genuinely useful behavioral fact beyond them: the note is visible to the team in the workspace. It does not mention that repeated calls duplicate the talking point (non-idempotent) or any permission requirement.

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, purpose stated first and the visibility side-effect second. No filler, nothing that fails to earn its place.

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

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

For a simple two-parameter add operation with an output schema and full annotation coverage, the description covers the essentials but omits the non-idempotent consequence of repeat calls and any note about who may add points to a digest. Adequate but with visible gaps.

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 the schema itself documenting 'the talking point, in plain text' and 'a digest id or slug from list_digests', so the baseline is 3. The description adds no format, length, or sourcing detail beyond what the schema already says.

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 (adds) and resource (a talking point to a digest), which cleanly separates it from the sibling note tools that target battlecards or signals. It does not, however, explicitly name those siblings as alternatives.

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

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

There is no guidance on when to use this tool versus add_signal_note or add_battlecard_note, nor any preconditions such as needing a digest id from list_digests. The agent must infer the usage context entirely from the noun 'digest'.

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

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

Annotations already declare this as a non-read-only, idempotent, open-world mutation with no destructive hint. The description adds context the annotations do not: the 10-page cap per competitor, the admin/paid-plan requirement, and the downstream effect that detected changes surface as signals.

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, followed by the constraint and the permission requirement. No sentence is redundant.

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

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

With an output schema present, the description needn't explain return values. It covers scope, limits, and permissions, 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 100%, so both parameters are already documented in the schema itself. The description only lightly reinforces this ('one more page', 'pricing page'), adding no format or sourcing detail beyond what the schema provides — the correct baseline of 3.

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 action — having Debriefing watch one additional page of an existing competitor — with a concrete example (pricing page). It clearly reads as adding a monitored page to a competitor that already exists, distinguishing it from add_competitor and remove_monitored_page.

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 the operative constraints (up to 10 pages per competitor, admin only, paid plan) that gate whether this tool can even be used. What it lacks is an explicit alternative route — e.g. directing an agent to add_competitor first if the competitor doesn't exist yet.

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 cover the safety profile (non-readonly, non-destructive, non-idempotent, openWorld), so the bar is lower. The description still adds real behavioral value: the note is visible to the team in the workspace and is hidden from public links unless those links include notes, which is meaningful disclosure for an openWorld write.

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, purpose front-loaded, zero filler. Each sentence carries distinct information (action, team visibility, public-link behavior).

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?

The tool has an output schema, full parameter documentation, and annotations, so the description needn't cover returns or safety. What it does cover — purpose and visibility semantics — is sufficient for correct invocation, though it omits any guidance on when this note tool is preferred over its siblings.

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

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

Schema description coverage is 100% and both parameters are already documented in the schema, so the baseline is 3. The description adds no format, length, or sourcing syntax beyond what the schema provides.

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 ('Adds') and resource ('a talking point to a signal'), and the resource noun distinguishes it from siblings like add_battlecard_note and add_digest_note. An agent can route to it 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?

There is no explicit when-to-use or when-not-use guidance, nor any reference to sibling note tools. Usage is implied by the name and the visibility sentence, but the agent gets no rule for choosing this over add_digest_note or add_battlecard_note.

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: no charge at creation, 24-hour expiry, 3-day trial charged only after day 3 for new customers, immediate charge for repeat customers, and a 14-day money-back guarantee once per customer. It also explains the idempotency_key retry contract. Minor tension with idempotentHint=false, but the description makes clear that only a repeated identical key suppresses the second effect, and each distinct call still mints a new link, so this is disclosure rather than contradiction.

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 behavior ('charges nothing', hand the link to the person) is front-loaded in the first sentences, and every later sentence carries distinct information. It is longer than typical but not padded; a couple of pricing sentences could be tightened.

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 authorization (admin only), lifecycle (expiry), billing consequences, retry safety, and the human hand-off rule, and an output schema exists so return values need no explanation. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100% and both enums are already documented, so the schema carries the load. The description adds business meaning around plan selection (trial vs immediate charge) but says nothing extra about 'interval' or the key beyond what the schema states.

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 ('Creates a Stripe Checkout link') plus the exact scope ('buys one Debriefing plan for this workspace'), which separates it from create_share_link and get_free_brief_link in the sibling list. An agent can identify the action 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 strong operational context: admin-only, the caller must hand the link over rather than pay it, and the link expires in 24 hours. It does not explicitly name an alternative tool or a 'when not to use this' case beyond the payment prohibition, so it falls just 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?

Goes well beyond the annotations by disclosing that the previous link stops working (the concrete destruction implied by destructiveHint=true), that Starter and paused workspaces are capped at 24 hours, and the exact retry contract for idempotency_key. These are non-obvious behavioral facts an agent cannot infer from the schema or hints.

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

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

Four short sentences, each carrying a distinct fact (access scope, replacement behavior, plan limits, retry contract), with the core purpose front-loaded and zero filler.

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

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

An output schema exists, so return values need not be explained, and the mutation/expiry/idempotency behaviors are all covered. The only real gap is that it never states who is permitted to create a share link or whether the resulting URL is retrievable elsewhere.

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 four parameters are already documented, including the expiry enum and idempotency_key semantics. The description reinforces the idempotency retry behavior and the plan-based expiry cap but adds little syntax or format detail beyond what the schema already states, so the baseline 3 applies.

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

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

States a specific verb and resource — 'Makes a public link to one signal' — plus the scope of access ('anyone with the address can open'). This is clearly distinct from siblings like create_checkout_link, get_free_brief_link, and get_public_brief, which an agent can rule out from the description alone.

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 operating context: a new link replaces the old one, plan tiers constrain expiry length, and idempotency_key must be sent for retries. It stops short of explicitly naming when to prefer an alternative sibling (e.g. get_free_brief_link or create_checkout_link), so no exclusions are 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?

Rich beyond the annotations: admin-only authorization, plan entitlement, a daily cap shared with the Debriefing app, and precise idempotent-retry semantics (same key returns the first answer, no second job, no second charge). The one weak point is that annotations declare idempotentHint=false while the description describes key-based idempotency; the text is the more accurate source, but the mismatch may leave an agent unsure whether a retry is safe without the key being identical.

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 scope are front-loaded in the first two sentences, and eligibility/cost/retry facts follow in a compact order. There is mild redundancy between 'does not act again' and 'It starts no second job and uses no allowance or daily cap a second time', though the latter does add the billing consequence.

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?

An output schema exists, so return values need no explanation, and the description supplies the pieces the schema and annotations do not: authorization level, plan requirement, shared rate-limit behavior, and safe-retry contract. An agent has everything needed to decide whether to call it and how to retry.

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

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

Only one parameter and schema description coverage is 100%, so the schema already explains the idempotency_key contract in the same terms ('Send the same key when you retry'). The description's 'Send an idempotency_key' and retry clauses largely restate that, adding the consequence (no second job, no extra allowance consumed) rather than new format or value guidance.

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+output: reads the company website and drafts the *empty* positioning fields (value propositions, differentiators, exclusions). The clause 'Filled fields stay as they are' plus 'Read the result later with get_company_profile' separates it from update_company_profile and from the read siblings without needing 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 clear invocation context: it fills empty fields only, and reading afterwards is routed explicitly to get_company_profile. It also states eligibility preconditions (admin only, paid plan or free first week) that gate whether the call should be made at all. It does not explicitly say 'use update_company_profile instead when you want to overwrite existing values', so the exclusion 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?

Discloses behavior the annotations do not: roughly one minute of latency, an async job that produces a result you read separately, a paid-plan requirement, and consumption of a shared daily cap with Debriefing. The idempotency semantics (a retry with the same key returns the first answer, starts no second job, and burns no second allowance) are spelled out precisely; this is key-scoped replay protection, which is compatible with idempotentHint=false meaning the call is not idempotent without a key.

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 cost-in-time, and every sentence carries a distinct constraint. The telegraphic fragment style ('The competitor needs finished research. Needs a paid plan...') is dense but slightly clipped.

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?

A paid output schema exists, so return values need not be explained, and the description correctly redirects to get_battlecard for results. Prerequisites, cost, latency, and retry behavior are all covered — nothing an agent needs before calling 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 in the schema, including the idempotency_key retry semantics. The description adds only a mild reinforcement ('Send an idempotency_key') and the competitor-quality prerequisite; 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 ('writes or rewrites the battlecard for one core competitor') and pins the scope to a single competitor. It is clearly distinguished from the read-side siblings by telling the agent to 'read it afterwards with get_battlecard'.

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 when-to-use ('now, instead of at the next cycle'), the follow-up action (get_battlecard), and concrete prerequisites (finished research, paid plan). The alternative path is named rather than 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds that the card is addressable by two different identifiers, which is useful context, but says nothing about behavior when both or neither id is supplied.

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

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

Two short sentences, zero filler, with the core purpose front-loaded ahead of the usage hint. 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 an output schema covering return values and annotations covering safety, the description only needs to convey purpose and selection; it does both. The one gap is the unresolved question of which id to prefer when both or neither are given.

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 both parameters already document their source list, so the schema does the heavy lifting. The description adds the OR relationship between the two ids, but since neither parameter is required it leaves the precedence/fallback 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 ('Gets one battlecard'), and the singular 'one' implicitly distinguishes it from list_battlecards. It does not, however, explicitly name the sibling it is not, so differentiation is inferred rather than stated.

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

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

Gives a usage scenario ('when the user prepares a sales call against a competitor'), which is clear context but soft and omits the alternative tools (list_battlecards for browsing, generate_battlecard for creation). No when-not or exclusion guidance is provided.

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 adds real scope information beyond them: this returns the workspace's own profile specifically (not a competitor's) and what content it holds. It stops short of anything about staleness, permissions, or who can read 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?

Two sentences, front-loaded with the core action and its field inventory. The second sentence is somewhat decorative — it explains how the data is consumed elsewhere rather than how to invoke the tool — but it is short and adds orientation, so it mostly 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 zero parameters, rich read-only annotations, and an output schema that documents return values, the description needs only to state what the tool returns and that it is the workspace's own profile — both of which it does. Complete enough to call correctly, missing only guidance on when to fetch 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?

The tool takes zero parameters and the schema is fully self-describing, so the baseline is 4. The description correctly implies a no-argument call by never introducing filtering or selection inputs, though it adds no parameter meaning because there is none to add.

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 ('Gets the workspace's own company profile') and enumerates what it contains: description, category, target customer, positioning lists, ICP. The phrase 'own company profile' cleanly separates it from get_competitor and the competitor-facing siblings, so an agent can pick it 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?

The only usage-flavored sentence, 'Debriefing reads every competitor move against it,' describes downstream system behavior rather than telling the agent when to call this tool. Nothing says when to prefer it over get_workspace or when company profile context is required, and no prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral context by naming the content categories returned (positioning, product, pricing, funding, traffic), which helps the agent judge whether the call will answer the user's question.

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

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

Two sentences, no filler; the payload enumeration leads and the usage cue follows. Nothing could be removed without losing 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 an output schema present, the description need not explain return structure, and the safety profile is carried by annotations. It omits any failure mode (e.g. unknown competitor_id), a minor gap for a read tool whose id must come from list_competitors.

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's description ('An id from list_competitors') already explains provenance. The tool description adds no syntax, format, or validity guidance beyond that, so the baseline 3 applies.

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

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

States a specific verb (gets) and resource (the dossier for one tracked competitor), then enumerates the payload: company facts, risk/opportunity, and stored reads. The 'one tracked competitor' scope distinguishes it from list_competitors without ambiguity.

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

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

'Use it when the user asks about one competitor in depth' gives a clear selection condition. It does not explicitly name list_competitors as the alternative for bulk browsing, but the depth/singular framing implies the boundary well enough.

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 establish readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond them: the admin-only access requirement and the routing rules (email and Slack get the finished cycle; Slack additionally gets the daily digest and enabled high-signal alerts).

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 purpose, which is good, but the latter half spends sentence-level detail describing channel routing outcomes that are already carried by the existing output schema, so not every sentence earns its place.

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

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

With an output schema present, the description need not explain return values, and annotations cover the read-only safety profile. The admin-only note fills the main remaining gap; adding a pointer to the sibling setters would make it fully complete.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. It correctly adds no parameter information, matching the baseline for a no-input tool.

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 ('Gets ... delivery settings') and enumerates what those settings cover: monitoring cycle cadence, plan-allowed cadences, and post destinations. It is clearly a read tool, but it doesn't explicitly differentiate itself from the sibling setters set_delivery_channels / set_monitoring_cadence or from get_plan_and_limits.

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 only usage guidance is the constraint 'Admin only.' There is no explicit statement of when to call this versus its write counterparts, though the read/write split with set_delivery_channels and set_monitoring_cadence is strongly implied.

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 safety is covered. The description adds genuine behavioral context the annotations don't: the default resolution to the newest digest when id is omitted. It does not cover error behavior (e.g., unknown id), 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?

Three short sentences, front-loaded with the primary retrieval behavior and followed by the default and usage hint. Every sentence carries information; no filler or redundancy.

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?

An output schema exists, so return values need not be described. The description covers both parameters' effects including the no-arg default, which is the main ambiguity for a two-optional-param getter. Minor gap: no mention of what happens with an invalid id.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond the schema by specifying the semantics of omitting both parameters (falls back to newest digest) and by tying type to a concrete value (daily_digest), adding meaning the schema property descriptions alone do 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 ('Gets one digest by id or slug') plus the no-argument behavior ('newest digest when no id is given'), which cleanly separates it from list_digests. An agent can tell it retrieves a single record rather than a collection without reading 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 an explicit trigger ('Use it when the user asks for the latest brief') and a parameter-selection hint ('Pass type daily_digest for the newest daily digest'). It lacks stated when-not-to-use conditions or a named alternative (e.g., list_digests), so it falls 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, and closed-world, so the safety profile is fully covered. The only added behavioral context is the return shape (excerpt + URL + date), which the output schema largely carries anyway.

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

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

Two tight sentences with zero waste: the purpose and the return content are front-loaded, and the usage trigger follows immediately.

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

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

For a single-parameter read tool with full annotation coverage and an output schema, nothing essential is missing. Only marginally incomplete in that it never explicitly ties the id back to search_signals in the description text.

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?

One parameter with 100% schema description coverage; the schema already documents signal_id as 'An id from search_signals'. The description adds no format or validation detail beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('Gets the evidence behind one signal') and describes the return content ('each source excerpt with its URL and date'). An agent can distinguish it from search_signals, which supplies the id, 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?

Explicit trigger: 'Use it when the user asks where a claim comes from.' That is clear when-to-use guidance, but it names no alternative or exclusion (e.g. bulk evidence retrieval), leaving the sibling-routing 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 readOnly/idempotent/non-destructive, and the description layers on genuinely non-obvious behavior: it returns links only, causes no side effects, enforces a 3-requests-per-24-hours limit, and requires the subject's consent before the email is sent. Rate limits and consent requirements are exactly the kind of context annotations cannot express, so this adds real value beyond structured fields.

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 then the constraint/consent rule. The 'only returns links / sends nothing / creates nothing' pair is deliberately redundant for emphasis and earns its place by forestalling a wrong write-action inference.

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-param read tool with an output schema, everything the agent needs is present: scope, side-effect absence, rate limit, consent requirement, and the pre-call check order. Return values need not be described since an output schema exists. Nothing material is missing.

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

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

Schema description coverage is 100% and the single `email` parameter is already documented as optional with its effect on the response ('how many free brief requests it has left today'). The description mostly restates that the email is used to check the limit and adds a consent qualifier, which is helpful but marginal. 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?

Specific verb+resource ("Gets the debriefing.io links" for free brief requests, workspace signup, plan comparison) with the exact scenario boundaries stated. It implicitly but clearly separates itself from write-oriented siblings such as request_free_brief, create_share_link, and create_checkout_link by declaring it 'only returns links' and 'sends nothing and creates nothing.' An agent can route correctly 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 a concrete precondition and sequencing rule: 'Send the person's email, with their consent, to check that limit before you give them the link.' That is an actionable when-to-use instruction. It stops short of naming the alternative tool (request_free_brief) for the case where the agent actually needs to submit a request, so it is clear context rather than full when/when-not/alternatives 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered structurally. The description adds real context beyond that: it enumerates the quota categories that can block an agent, states trial and guarantee windows, notes cancellation status is informational only, and mentions the included pricing link.

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 statement is front-loaded, but everything after the colon is one very long run-on enumeration that overlaps what the existing output schema already exposes. A short grouped list (quota limits / trial and billing state / cancellation flag) would deliver the same value in less 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?

With an output schema present, return values need no explanation, and the description still sketches the payload shape and the read-only boundary. An agent has enough to decide to call it and to interpret results without further reading.

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?

Zero parameters, so the baseline is 4; there is nothing for the description to clarify and it correctly makes no parameter claims. No gaps to compensate for.

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?

A specific verb plus resource ('Gets the workspace plan and every limit') with an explicit inventory of covered limits: competitor slots, research allowance, battlecard caps, trial end, guarantee, cancellation state. This clearly separates it from get_workspace and get_delivery_settings, which cover different configuration domains.

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?

'Every limit an agent runs into' signals the use case (check quotas before they block work), and the parenthetical '(read only: an admin cancels in Billing)' explicitly excludes the mutation path and points elsewhere. It does not explicitly contrast with the nearest siblings such as get_workspace, 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 the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real context: the tool needs no Debriefing account, and it describes the shape of the returned brief content.

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 with zero filler: purpose and return contents first, then addressing modes, then the fallback rule. Every sentence carries information an agent needs to invoke the tool correctly.

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 an output schema present, return values need not be detailed, and the description still covers addressing modes and the no-account requirement. Minor gaps remain around failure behavior (e.g., unknown slug/company) and whether all three params can be combined, but nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds precedence semantics the schema does not state: url alone, or company_slug + slug together, or company_slug alone resolving to the newest brief. That combination/fallback logic is genuinely beyond the field-level 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?

States a specific verb and resource ('Gets one competitive brief that Debriefing published on debriefing.io') and enumerates exactly what is returned: summary, findings with category and date, and numbered sources with URLs. This clearly separates it from siblings like search_public_briefs (plural, discovery) and get_free_brief_link.

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

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

Explicitly routes the agent: name the brief by URL, or by company_slug + slug from search_public_briefs, and notes the company_slug-only fallback returns the newest brief. It names the sibling that supplies slugs and states the account-free condition, though it gives no explicit when-not-to-use 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, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds orienting behavior beyond that—telling the agent it reveals held scopes and role, which frames why to invoke it early. It does not describe pagination or limits, but for a zero-arg read that is minor.

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

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

Two sentences, front-loaded with the verb and resource, and the field list is the necessary payload of an orientation call. The trailing usage cue is a single clause that earns its place; 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 an output schema present, return values needn't be explained, and annotations already carry the safety profile. For a zero-arg read the description gives the agent everything needed—what it returns and when to reach for 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?

The tool takes zero parameters, so the parameter-semantics baseline is 4. There is no argument syntax or format an agent could misinterpret, and the enumeration of returned content is not a parameter concern.

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 (Gets) and resource (the Debriefing workspace this connection works on) and enumerates the returned content: name, website, identity/role, scopes, and plan. This clearly differentiates it from near-siblings like get_plan_and_limits and list_members without needing to open 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?

"Call it first when you are not sure what you may do" gives an explicit trigger condition and positions the tool as the orientation step. It stops short of naming when-not-to-call or a specific alternative, so it is clear context rather than full when/when-not/alternative 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description discloses invite lifetime (7 days), resend semantics, authorization and plan requirements, and the idempotency contract (same key returns the first answer and does not act again). These are the exact behavioral details an agent needs before invoking a mutating, email-sending tool.

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

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

Five short sentences, each carrying distinct information (action, duration, resend rule, prerequisites, idempotency), with the core action front-loaded. No filler or repetition.

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

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

An output schema exists, so return values need not be described; the description covers everything else an agent must know (permissions, plan, invite expiry, retry safety). Nothing material for correct invocation 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 50%, and the one documented parameter (idempotency_key) is already explained by the schema text, which the description largely echoes. The description never states explicitly that `email` is the invitee address, so it adds only marginal meaning beyond structured fields; 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?

The description names a specific verb and resource ('Sends an email invitation to join the workspace as a member'), which is unambiguous and clearly distinct from read-oriented siblings like list_members or get_workspace. 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 gives concrete preconditions ('Admin only, on a paid plan') and clarifying conditions for repeat use ('Inviting the same address again sends a fresh email'), which is strong context. It stops short of naming alternatives such as create_share_link for granting access without an email invite, so it is not a full when/when-not routing statement.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds useful domain context ('one for each competitor that has one', what a battlecard holds) but says nothing about pagination, ordering, or empty-result behavior.

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

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

Two sentences, both earning their place: the first gives scope and cardinality, the second defines the returned object. Nothing is padded and the key scoping fact is front-loaded.

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

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

With an output schema present, the description needn't explain return values, and with zero params there are no input gaps. It covers scope and cardinality but omits ordering/pagination, a minor gap for a listing 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 takes zero parameters, so there is no parameter semantics to document and the baseline is 4. The description correctly spends no text on inputs.

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 (Lists) and resource (battlecards) and scopes it to 'Debriefing wrote for this workspace', which clearly separates it from the sibling get_battlecard. It even defines what a battlecard is, so an agent can route to it confidently.

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 read-all use case and notes the one-per-competitor shape, but never states when to prefer this over get_battlecard or other siblings. No exclusions or alternative routing are given, so usage is only implied.

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 bar is lower. The description usefully adds the workspace scoping ('this Debriefing workspace tracks') and the returned field set, though it does not discuss pagination or empty-workspace behavior.

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

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

Two tight sentences, front-loaded with the action and scope, followed by the high-value routing hint about competitor_id. No filler.

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

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

An output schema exists, so return details needn't be spelled out, and annotations cover safety. For a zero-param list tool, the description provides purpose, scope, key return fields, and the canonical for tools like get_competitor.

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

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

Zero parameters, so baseline is 4. The description correctly implies no filtering input is required, consistent with an empty schema, and adds value by naming the output fields an agent will rely on.

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 (Lists) and resource (competitors this Debriefing workspace tracks), and enumerates the returned fields (id, name, website, category). It is clearly distinguishable from siblings like get_competitor (single) and add_competitor (mutation).

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 says to 'Call it first to get the competitor_id that other tools take,' which gives a clear when-to-use context and a downstream dependency on siblings. It does not name specific alternative tools or state when not to use it, keeping it short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, covering the safety profile. The description adds useful context that results are scoped to the current workspace and ordered newest first, plus a definition of a digest, though it does not explain pagination or limit behavior beyond what the schema shows.

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

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

Two sentences, front-loaded with the action and scope, followed by a useful definition of a digest. The definition earns its place by clarifying the resource, though the sentence could potentially be trimmed.

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 rich annotations and an output schema, the description does not need to explain return values. It gives enough context for a list operation: scope, ordering, and filtering. The main remaining gap is lack of detail on the limit parameter, which the schema partially covers with bounds.

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 50%: the type parameter already has a schema description, while limit has none. The description adds that type acts as a filter and gives an example, but it does not compensate for the undocumented limit parameter.

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 digests for the workspace, newest first, and defines what a digest is. However, it does not explicitly differentiate this list tool from the sibling get_digest, which retrieves a single digest.

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 indicates that results can be filtered by type, such as daily_digest, which implies a browsing use case. It does not say when to use this instead of get_digest or search tools, and it offers no exclusions or prerequisites.

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 safety is covered. The description adds a genuine trait beyond them: output varies by caller privilege, since an admin additionally sees pending invitations. That is exactly the kind of context annotations cannot express.

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 zero filler; the core purpose is front-loaded and the permission nuance follows. Every clause 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 an output schema present, return values need not be explained, and with zero parameters there is no input surface to document. The one gap is that the description says nothing about ordering or whether the list is bounded, which is minor for this 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 takes zero parameters, so there is nothing for the description to clarify and the baseline of 4 applies. No parameter information is missing because none exists.

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 ('Lists the people in the workspace with their roles'), which is immediately distinguishable from invite_member among the siblings. It stops short of explicitly naming an alternative or boundary, but the purpose 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?

Usage is only implied by the verb 'Lists' – there is no statement of when to reach for this versus invite_member or get_workspace. The clause about admins seeing pending invitations hints at context but is a behavior note rather than 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 readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds the team-wide visibility scope and the unpin semantics, but does not explain what 'destructive' means here or note any 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?

A single front-loaded sentence covering both the action and the inverse, with no wasted words. The primary behavior comes first and the edge case second.

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?

An output schema exists, so return values need not be explained, and the annotations carry the mutation/idempotency profile. For a two-parameter toggle, both directions of the operation and its team-wide effect are 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 coverage is 50%: digest_id is documented in the schema, but the 'pinned' boolean is not. The description fills that gap by explaining that 'pinned false' removes the pin, which gives the undocumented parameter real meaning beyond its default value.

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 (pins/removes pin) and resource (a digest) with the added scope of 'for the whole team.' The resource noun plus the sibling set (pin_signal, list_digests) makes the target unambiguous, though it never explicitly positions itself against pin_signal.

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 both modes of the tool ('pinned false' unpins), which tells the agent how to invoke each direction, but gives no guidance on when to pin vs. rate a digest or when to prefer other siblings. Usage is implied by the toggle rather than framed as a 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=false, destructiveHint=true, idempotentHint=true and openWorldHint=true, so the mutation/repeatability profile is covered. The description adds the genuinely useful fact that the pin is visible to the whole team, but says nothing about required permissions or how unpinning affects existing team state.

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

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

A single sentence that front-loads the primary action and appends the toggle behavior. Nothing is wasted and nothing essential is buried.

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

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

An output schema exists, so return values need not be described, and annotations carry the safety profile. The remaining gap is the absence of any routing against pin_digest, but for a two-parameter toggle the description is otherwise sufficient.

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% — signal_id is documented in the schema but pinned is not. The description compensates by defining pinned=false as the unpin action (default true), giving the otherwise-undocumented parameter concrete 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 (pins) and resource (a signal), plus the inverse action via pinned=false. It does not differentiate itself from the sibling pin_digest, which shares the same verb, so an agent must infer the target distinction from the name alone.

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 conveys when the tool is used (to pin or unpin) and that the effect is team-wide, but it offers no explicit when-not guidance or named alternative despite the near-identical sibling pin_digest. Usage is implied rather than routed.

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?

'A new rating replaces your old one' indicates upsert semantics, but the description contradicts the destructiveHint=true annotation by not flagging that this is a destructive overwrite of prior rating state. Other behaviors (auth, whether removing a rating is possible) are unstated.

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 primary action, zero filler.

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

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

Output schema exists so return values needn't be described, but for a destructive-rated mutation the description omits any permission or effect context and gives no clarity on whether score and comment can be cleared.

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 67% and covers digest_id and comment; the description adds no meaning about the score/comment combination semantics beyond what's already implied by 'or 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?

States a specific verb (scores) and resource (a digest) plus the 1-5 range, distinguishes itself from siblings like rate_signal and add_digest_note by acting on digests with a numeric score.

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?

Implies usage from 'or both' and 'replaces your old one' but doesn't say when to rate vs use add_digest_note or get_digest, nor when not to use it.

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, and the description usefully explains the replacement semantics ('A new rating replaces your old one'), which contextualizes idempotency. However, it does not disclose the write/destructive nature of re-rating or what the old rating's removal implies, so it adds only partial behavioral context 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?

Three short sentences, front-loaded with the purpose and followed by the conditional field guidance and replacement rule. No filler, though the opening phrasing is a touch indirect.

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?

An output schema exists so return values needn't be explained, and the description covers the main conditional behavior. Minor gaps remain around whether reasons is mandatory when useful=false and how re-rating interacts with prior data, but overall it is adequate for a 4-param tool.

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

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

Schema coverage is 50%: signal_id and reasons are documented in the schema itself, while useful and comment are not. The description adds value by tying reasons and comment to the useful=false case, but adds nothing for the required 'useful' boolean, so it only partially compensates.

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 action (rate/tell whether a signal was useful) on a specific resource (a signal), which distinguishes it from the sibling rate_digest. It's slightly indirect by framing it as 'Tells Debriefing whether' rather than 'rate the signal', but an agent can identify the operation.

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 conditional guidance for the negative case ('For not useful, add reasons and a comment'), which implies when to supply optional fields, but it never states when to use this tool versus rate_digest or other rating-adjacent siblings, nor any prerequisites.

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 context the annotations do not carry: it consumes one update from the weekly research allowance, requires admin rights, and explains the retry/side-effect budget ('starts no second job and uses no allowance or daily cap a second time'). The only weakness is that this retry-dedup story sits in mild tension with the declared idempotentHint=false, leaving a small ambiguity about how retries are actually treated.

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 action and timing, then cost, auth, and idempotency facts. The final sentence ('starts no second job and uses no allowance or daily cap a second time') partially repeats the prior retry sentence, a mild redundancy that keeps it from a 5.

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 annotations covering the safety profile, an output schema present, and 100% parameter coverage, the description still supplies the non-obvious facts an agent needs: cost in allowance, admin restriction, and retry behavior. Nothing material to correct invocation is missing.

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

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

Schema description coverage is 100% and the single idempotency_key parameter is fully documented in the schema itself (max/min length, purpose). The description restates the key's retry semantics but adds no syntax or format detail beyond it, so the baseline 3 applies.

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

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

States a specific verb and resource ('Refreshes the research on the core watchlist') plus the timing nuance ('now, instead of at the next cycle'). An agent can tell this is an on-demand refresh versus the scheduled cycle. It does not explicitly separate itself from siblings like research_competitor or set_monitoring_cadence, so it stops short of 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?

'now, instead of at the next cycle' gives a clear condition for choosing this over waiting on the scheduled refresh, and 'Admin only' flags a prerequisite. No explicit exclusions against sibling tools are stated, so it is clear context but not full when/when-not 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 cover the safety profile (destructiveHint=true, idempotentHint=true), but the description adds what the annotations cannot: that monitoring stops while history is retained, and that the operation is gated to admins on a paid plan. That is exactly the kind of consequence and authorization context an agent needs before firing a destructive call.

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

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

Two short sentences, zero filler, with the effect and the access constraint front-loaded rather than buried. Every clause carries information the agent needs.

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 an output schema present, return values need no explanation, and the description covers effect, history retention, and authorization. Nothing required to invoke this correctly is missing.

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

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

Schema description coverage is 100% and the single parameter already carries its own guidance ("An id from list_competitors"). The description adds only the implication that exactly one competitor is targeted, so the schema does the heavy lifting — baseline 3.

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 ("Takes one core competitor off the watchlist") and the word "core" implicitly scopes it against the sibling remove_monitored_page. An agent can distinguish this from add_competitor, rename_competitor, and remove_monitored_page without opening a schema.

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

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

Gives a clear precondition set — "Admin only, on a paid plan" — which tells the agent when this call is even permissible. It does not explicitly name alternatives or spell out a when-not case beyond the plan/permission gate, so it falls short of a full 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the mutation profile is covered. The description earns credit by adding the authorization and billing constraints (admin-only, paid plan) that the annotations don't express, though it never says what actually happens to collected data or history.

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

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

Three short sentences with the action first, then the identification mechanism, then the gating constraints. Nothing is padded and nothing is buried.

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

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

With an output schema present, return values need no explanation, and the description covers action, identification, and permissions for a 3-parameter tool. The one residual gap is that it doesn't clarify whether page_id and url are alternatives or both accepted alongside competitor_id.

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 67% (url is undocumented in the schema), and the description compensates by telling the agent the page can be named 'by page_id or url'. That is real added meaning, since the schema never expresses the either/or identification choice.

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 ('Stops watching a page') and scopes it to 'a page that someone added on a core competitor', which subtly separates it from remove_competitor in the sibling list. It stops short of explicitly naming the inverse tool, but the operation 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?

It states the prerequisites plainly ('Admin only, on a paid plan'), which is exactly the kind of gating an agent needs before calling. It doesn't spell out when-not to use it or point to an alternative, so it falls 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?

The annotations declare destructiveHint=true and idempotentHint=true, but the description doesn't explain what makes it destructive or how idempotency manifests. 'Admin only' adds a permission requirement not in annotations, which is valuable 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?

Two short sentences that are front-loaded with the core action and constraint. No wasted words.

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

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

Given the mutation tool complexity with annotations, an output schema exists so return values needn't be explained. However, the description lacks details on what 'display name' means, potential side effects, or why it's destructive, leaving some gaps.

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

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

Schema coverage is 50%, with competitor_id described as 'An id from list_competitors' in the schema but no parameter details in the description. The description doesn't compensate for the undocumented 'name' parameter.

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 ('Changes') and resource ('display name of one tracked competitor'). Distinguishes from sibling remove_competitor and add_competitor by focusing on the rename operation.

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 'Admin only' note provides a usage constraint, but there's no guidance on when to use this vs alternatives like add_competitor or remove_competitor. The condition is implied but not explicit.

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: it discloses that Debriefing researches the company and competitors, emails the brief to the person, and that the person must sign up with the same email to claim it. The one-email-one-brief rule and repeat-returns-same-URL behavior give the agent real side-effect and idempotency context that the hints only imply.

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

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

Front-loaded with purpose and return value, then prerequisites and edge behavior. Four dense sentences where each carries information, though the consent sentence could be tightened 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?

With an output schema present, return-value documentation isn't needed, and the description covers the remaining gaps: preconditions, consent, external side effects, and idempotency. An agent has everything required to invoke 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 already 100%, so the baseline is 3, but the description adds meaning on top: it reinforces the consent requirement for person_consented and explains the uniqueness/idempotency semantics of email ('one email address gets one brief... a repeat returns the same claim URL').

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 (requests a free competitive brief) plus the target audience (a person with no Debriefing account) and the return (a claim URL). It clearly separates this creation/request flow from a retrieval flow, though it never names the nearby sibling get_free_brief_link 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 a concrete precondition for use ('a person who has no Debriefing account') and an explicit behavioral rule ('Ask the person first: send person_consented true only after they agree'). It stops short of naming which tool to use instead when the person already has an account.

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

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

Adds substantial context beyond the annotations: the Admin-only permission requirement, the consumption of one weekly allowance update, the idempotency-key retry semantics, and the guarantee that a retry neither starts a second job nor double-charges the allowance or daily cap. This is exactly the operational cost and auth detail the readOnlyHint/openWorldHint annotations cannot convey; the annotation idempotentHint=false reflects raw call behavior, while the description correctly scopes idempotency to key reuse.

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 its precondition, and the operational constraints are packed densely. The final sentence ('It starts no second job and uses no allowance or daily cap a second time') largely repeats the preceding idempotency sentence, which is minor redundancy rather than noise.

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 an output schema, the description covers permissions, cost, precondition, and retry safety, so return values need no explanation. The one gap is failure-mode behavior: it does not say what the caller gets back if the competitor already has research or if the allowance is exhausted.

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 both competitor_id (sourced from list_competitors) and idempotency_key are already fully documented in the schema. The description restates the idempotency-key contract and nothing more, so the baseline 3 applies.

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

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

States a specific verb and resource ('Starts the first research on one core competitor') plus the eligibility precondition ('that has none yet'), which no sibling tool performs. An agent can distinguish this from read-only siblings like get_competitor or list_competitors 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 clear usage context: it applies to a core competitor with no existing research, it requires Admin, and it consumes one weekly research allowance update. No alternative tool is named, but no sibling performs research at all, so there is no routing ambiguity to resolve. It also does not say what to do if the competitor already has research beyond noting no second job starts.

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, destructive, idempotent, and closed-world behavior, so the bar is lower. The description adds real value beyond that by disclosing the private visibility scope ("Only you see your saved signals") and by explaining that the destructive-looking operation is actually a reversible toggle via saved=false.

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

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

Two short sentences, zero filler, with the core action and its inverse front-loaded and the privacy caveat placed last. Every clause carries 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?

An output schema exists, so return values need no explanation, and the description covers both parameters plus the visibility scope. It is close to complete for a simple two-parameter toggle, with only cross-tool routing 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 coverage is only 50%: signal_id is documented in the schema ("An id from search_signals or what_changed"), but `saved` has no schema description. The description compensates by defining saved=false as the removal switch, covering the undocumented parameter and adding meaning beyond the bare boolean.

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+resource (save a signal) and additionally discloses the inverse operation (removal via saved=false), which is more than a restatement of the title. It doesn't explicitly name or distinguish itself from signal-adjacent siblings like pin_signal or rate_signal, so an agent must infer the difference from semantics alone.

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 dual direction (save vs. unsave) is stated, which implies when each mode applies, but there is no explicit guidance about when to use this versus pin_signal or rate_signal, nor any prerequisites. Usage is implied rather than routed.

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 openWorld=false, so the safety profile is covered. The description adds real value beyond that: return fields (title, excerpt, URL), ranking ('best match first'), and the no-account requirement. This is solid added context, though no mention of rate limits or result-count behavior.

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

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

Three tight sentences, front-loaded with the verb and scope, then return shape, then the account requirement. No filler; every sentence carries 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 an output schema present, the description needn't explain return values, and annotations cover safety. It still supplies scope, content types, ranking, and auth-free access. The only minor gap is not distinguishing itself from sibling search tools.

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 67%: query and collection are documented in the schema, but limit is not. The description adds no parameter-level detail (no query syntax tips, no limit guidance), so it does not compensate for the gap and simply rests on the schema baseline.

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 ('Searches the public competitive intelligence library on debriefing.io') and enumerates the content types covered (guides, glossary, comparisons, alternatives, profiles, intel posts). It clearly signals a read-only search, but it never names its closest siblings (search_public_briefs, search_signals) to differentiate scope precisely, so the agent must infer the boundary.

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 context is implied by 'public competitive intelligence library' and the note that it 'Needs no Debriefing account', which usefully tells the agent no auth is required. However, there is no explicit when-to-use vs alternative guidance against search_public_briefs or search_signals.

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 establish the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds genuinely useful context beyond that: newest-first ordering, that briefs are dated and cite public sources, and that no Debriefing account 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?

Four tight sentences, front-loaded with purpose, then filtering, then the no-arg default, then the auth note. No filler.

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

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

With an output schema present and rich annotations, the description only needs to supply intent and usage context, which it does: what is searched, how to filter, default behavior, and the no-account requirement. Nothing an agent needs to invoke it 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 67% and the description clarifies that the company parameter accepts a name, slug, or domain, extending the schema's examples. The limit parameter is left to the schema, whose max of 50 is self-explanatory.

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 (Searches) and resource (competitive briefs Debriefing publishes about named companies), plus the source domain and default ordering. This distinguishes it clearly from the singular get_public_brief 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?

Explains how to filter (by words and by company name/slug/domain) and that no arguments returns the newest briefs, plus that no account is needed. It never explicitly routes to alternatives like get_public_brief or other search_* tools, so it stops short of the 5 bar.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds the newest-first ordering and that results carry source evidence, but says nothing about pagination, the 'open' vs other signal states, or the default/max result count.

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 filler: purpose and ordering first, then the filter set, then the usage trigger. Every sentence carries 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?

An output schema exists, so return values need not be spelled out, and the definition covers the domain concept, filters, ordering, and usage trigger. The remaining gap is that limit (min 1, max 50, no default stated) is unexplained anywhere.

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 60% (limit and severity lack descriptions), so the description does useful compensating work: it names competitor_id, severity with its low/medium/high levels, a text query, and a since time. Only the limit parameter is left entirely undocumented in both places.

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 ('Searches open signals') plus ordering ('newest first'), and defines the domain term 'signal' as a competitor move with source evidence so an agent knows what is being returned. It does not explicitly contrast itself with the nearby sibling what_changed, so sibling differentiation is only partial.

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

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

Gives a clear trigger ('Use it when the user asks what a competitor changed') and enumerates the filter axes available. There are no stated exclusions or named alternatives among the many sibling search/list tools, which keeps it short of a 5.

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

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

Annotations already declare idempotentHint=true, destructiveHint=true and openWorldHint=false; the description adds the crucial partial-update contract ('Only the switches you send change') plus the auth/plan/Slack-connection requirements. It stops short of spelling out the destructive consequence of turning a channel off, which the annotations only hint at.

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 every subsequent sentence carries information (scope of change, plan/connection requirements, where routing rules live, admin restriction). Six short sentences is slightly more than minimal, but none are filler.

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

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

An output schema exists so return values need not be described, and the description covers the behavioral, authorization and precondition surface an agent needs before invoking a 4-boolean admin mutation. The only real gap is the unnamed read sibling for inspecting current state.

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 75% schema coverage the baseline is 3, but the description adds relational meaning the schema lacks: slack_alerts and slack_digest are conditional sub-switches that only matter when slack is on, and Slack receives the finished cycle regardless. The email flag still has no description anywhere.

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 ('turns ... on or off') on a specific resource (delivery by email and Slack), and it enumerates the concrete sub-channels (finished cycle, daily digest, high signal alerts). This clearly separates it from the read-side sibling get_delivery_settings.

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 real preconditions: 'Admin only', 'Slack needs Growth or above and a Slack connection made in the app', and notes that channel routing rules live in the app rather than here. It doesn't name get_delivery_settings as the read counterpart, so the when-to-use-vs-alternative guidance is implied rather than explicit.

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 the mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=true), so the bar is lower. The description adds genuinely useful context beyond them: admin-only permission requirement and paid-plan gating, plus the plan-driven validation of allowed cadences. It does not explain why the change is flagged destructive or what the cadence change affects operationally.

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 filler, and the core action is front-loaded before the gating information. Every sentence carries distinct information.

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

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

An output schema exists, so return values need no explanation, and the description covers purpose, allowed-value discovery, and access prerequisites. The one gap is that destructiveHint=true is unexplained for what looks like a benign settings change, leaving the agent without impact context.

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 parameter's schema already documents that the value comes from get_delivery_settings, so baseline is 3. The description echoes the same pointer but adds no new format, default, or validity detail beyond what the schema provides.

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 ('Sets how often Debriefing runs a monitoring cycle') that clearly distinguishes it from the read-only sibling get_delivery_settings and from set_delivery_channels. An agent knows immediately what the tool mutates.

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 real selection context: it names get_delivery_settings as the source of allowed cadence values and states prerequisite conditions (admin only, paid plan). It does not explicitly say when not to use it versus siblings like set_delivery_channels, but the conditions that gate usage are 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 declare destructiveHint=true and idempotentHint=true, and the description meaningfully extends them: 'Only the fields you send change' (partial-update semantics), 'The lists replace the old lists' (replace vs. merge, a critical and non-obvious behavior), plus the admin-only and brief-lock constraints. This is substantive behavioral context beyond the structured fields.

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?

Five short, front-loaded sentences with zero filler. The most consequential constraint (partial update and list replacement) comes first, followed by access and locking conditions. Every sentence earns its place.

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

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

With an output schema present, return values need no explanation, and the description covers the mutation semantics, auth requirement, and lock condition for a 16-param write tool. The only gap is per-field meaning for the many undocumented 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 description coverage is only 25%, so most of the 16 fields (name, industry, website_url, etc.) are undocumented in the schema. The description compensates with the two most important semantics — partial update and list replacement — but does not clarify any individual field's meaning. Baseline 3 is appropriate.

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

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

The description names a specific verb ('Changes') and resource ('fields of the workspace's company profile'), so an agent can immediately tell it apart from the read-only get_company_profile sibling. It stops short of explicitly naming an alternative, but the mutation verb 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?

It supplies real usage constraints: 'Admin only' states a permission prerequisite and 'Locked while the first brief runs' states a timing restriction, both of which help decide whether the call can succeed. However it never says when to prefer this over a sibling or when not to call it, leaving that 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?

Goes far past the annotations (destructiveHint=true, idempotentHint=false) by disclosing the re-read side effect, the cross-app daily-cap accounting, the first-brief lock, and precisely what a duplicate idempotency_key does — returns the first answer, starts no second job, spends no allowance. The key-based retry semantics reconcile with idempotentHint=false rather than contradicting it: idempotency is caller-supplied, not intrinsic.

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 its side effect, then a series of short constraint sentences that each carry distinct information. It is staccato and runs long, but no sentence is filler and nothing important is buried.

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

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

A destructive, quota-consuming mutation with a mandatory idempotency key, fully covered: mutation semantics, partial-update behaviour, preconditions, lock state, and retry behaviour are all stated. An output schema exists, so omitting return-value detail is appropriate.

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 earns above it with "Only the dimensions you send change; an empty list clears one" — PATCH-style partial-update versus clear semantics that the schema's bare array descriptions do not convey. The idempotency_key advice duplicates the schema text rather than adding to 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?

"Sets the ideal customer profile" is a specific verb+resource, and the added clause about re-reading competitor overlap captures a side effect that no other sibling has. It is distinguishable from update_company_profile/get_company_profile by resource name, though it never explicitly routes the agent away from those neighbours.

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 unusually concrete when-not conditions: admin-only, requires a paid plan or the free first week, blocked while the first brief is running, and consumes a shared per-workspace daily cap. An agent can decide before calling whether it is permitted to act, which is exactly what this dimension demands.

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: that results span three entity types and are scoped by the 'since' time, which is what makes this tool distinct from a plain list.

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

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

Two tight sentences, front-loaded with what it returns and followed by the use case; nothing wasted. The trailing 'such as since the user's last visit' is mildly redundant with 'since a time', keeping it from a 5.

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 an output schema present and annotations covering the safety profile, the description only needs to convey scope, content, and intent, all of which it does. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so both parameters (since, limit) are already documented, including that limit caps rows per kind. The description only echoes 'since a time' and adds no format or semantics 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 (Lists) and resource (everything new in the workspace) and enumerates the three record kinds returned: signals, digests, and battlecards. This distinguishes it from the per-type siblings (list_digests, search_signals, list_battlecards) as a cross-entity activity feed.

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?

"Use it to catch up, such as since the user's last visit" gives a clear usage context, and the aggregate scope implicitly frames it against the per-entity list tools. No explicit when-not or named alternative, 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.