Bullpen

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries real weight here: it discloses the consent precondition, the role requirement, and that the acceptance is 'recorded with this connection,' signaling a durable, attributable legal record. It does not state whether acceptance is reversible or what happens on a duplicate call, which matters for a consent-record action.

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 the safety-critical precondition front-loaded ahead of mechanical details. Minor redundancy in restating the full-name requirement that the schema already covers, but 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?

All three required parameters are documented in the schema, and the description supplies the consent, role, and attribution context that the annotations do not. No output schema exists, but the missing piece is what a successful acceptance returns and whether it can be undone.

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

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

Schema coverage is 100%, and the schema already documents the version source (get_outbound_agreement) and the 'as they typed it' wording. The description restates the name requirement and reinforces the intent of person_agreed rather than adding new meaning, so the baseline 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 states a specific verb and resource (accept the outbound compliance agreement) and makes the contrast with get_outbound_agreement clear through the precondition that the person must have read it first. It stops short of naming the sibling by name, so an agent must infer the read-then-accept sequence.

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?

Strong gating guidance: 'ONLY after they have read it and told you they agree' plus a role restriction ('Admin or manager only') defines both when and when-not to call. The alternative path — fetching the agreement first via get_outbound_agreement — is only implied, not named.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds two pieces of genuine behavioral context beyond that: responses are attributed 'with sources', and results are filtered by 'the key's role', which tells the agent answers may be incomplete due to permissions. It stops short of describing handling of unanswerable questions or any latency/rate 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?

One sentence, front-loaded with the core action, and the parenthetical '(calls, notes, docs)' and the trailing permission qualifier both earn their space. Dense but not bloated.

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

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

For a one-parameter read-only tool with annotations covering the safety profile and no output schema, the description supplies scope, source attribution, and the role-based access constraint. Nothing essential to correct invocation is missing, though a pointer to the closest sibling would complete 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?

There is a single parameter with 100% schema description coverage, so the schema already documents it and a 3 baseline applies. The description adds only indirect meaning about the question (it should be answerable from workspace knowledge and is constrained by key role), not anything about form or phrasing.

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: answer a question from the workspace's own knowledge, and enumerates the source types (calls, notes, docs). This implicitly scopes it away from external-research siblings like research_company and find_companies, but it never names or contrasts with the near-identical ask_herman, so an agent must infer the split.

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 scope phrase 'from the workspace's own knowledge' implies when to reach for it (internal facts rather than web lookups), which is useful selection signal. However, there is no explicit when-to-use/when-not guidance and no mention of ask_herman, the most obvious alternative in the sibling list, leaving that choice 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?

With readOnlyHint=false and openWorldHint=true, the annotations only say 'may have effects and reaches outside systems' — the description supplies the critical missing mechanic: anything external is returned as a pending action with an id and nothing is emitted until confirm_herman_action. That two-step staging behavior is exactly the context an agent needs to avoid assuming a real-world send already happened. It also reconciles the apparent tension between a side-effect-free feel and the write-ish annotations.

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

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

Two sentences, front-loaded with the actor and its scope, then immediately the staging rule and the follow-up tool. No filler and no restatement of the title or schema.

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

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

For a single-parameter natural-language router with no output schema, the description covers purpose, the staged-result shape ('pending action with an id'), and the required next step. What is left out is failure/ambiguity handling — e.g. what happens if Herman cannot map the request or whether the reply includes clarifying questions — which would matter for a free-text entry point. Overall it is nearly 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?

Schema coverage is 100% and there is a single required string, so the baseline is 3. The description adds beyond the schema's 'What you want, in plain words' by giving concrete example payloads (status, finding companies, running campaigns, sending the crew to call), which shows the expected granularity of a natural-language request. It does not discuss ambiguity resolution or follow-up clarification, so not a 5.

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

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

The description names a specific resource — Herman, the manager agent that runs the bullpen — and gives a concrete capability list (status, finding companies, running campaigns, sending the crew to call). This makes it distinguishable from direct sibling tools like create_campaign, find_companies, or send_email, which cover one slice each while this is the natural-language orchestrator. It stops short of an explicit 'this is the router, prefer it over calling the individual tools' statement.

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 conveyed through the enumerated domains an agent can ask about (status, prospecting, campaigns, calling), which implicitly tells the caller when this tool applies. It does not spell out exclusions or explicitly route an agent between ask_herman and the direct action tools when both could serve. The handoff to send-confirmation is clear.

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

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

The readOnlyHint=true annotation is consistent with an informational tool, and the description adds genuine value beyond it by disclosing that no API key is required and that it should be the first call for keyless agents. The two signup paths, free $10 credits with no card, or paying over MPP, give an agent real behavioral context about the onboarding state machine. It does not describe the shape of the returned content, which is the main remaining gap.

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

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

The content is compressed into two sentences with the key routing instruction placed where an agent will see it, and no filler. Minor cost: the pricing clause ('free with $10 of credits (no card) when your person signs in, or by paying over MPP') is dense, uses the undefined acronym MPP and the vague 'your person', which slightly dilutes readability despite the brevity.

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 zero-parameter, no-output-schema informational tool, the definition covers purpose, cost model, and the exact condition under which an agent should invoke it. Nothing essential to deciding whether to call it is missing. Only the nature of the returned text is unstated, a modest omission given the tool's simplicity.

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

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

The tool takes zero parameters, so there is no parameter meaning for the description to add. The baseline of 4 applies for a schema-free call signature, and nothing in the description misleads about 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?

The description opens with a concrete enumeration of what this tool returns knowledge about: what Bullpen does, its cost, and how to obtain a workspace. That clearly separates it from action siblings like bullpen_signup, buy_credits, and credits_status, which perform the steps this tool only explains. It is clear but not maximally sharp, since the phrasing is content-oriented ('what Bullpen does') rather than a crisp verb+resource statement.

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 this first if you have no key' is an explicit, conditional trigger that tells an agent exactly when to reach for this tool. The parenthetical '(No API key needed.)' reinforces that it is the correct entry point for unauthenticated agents. It stops short of naming alternatives such as credits_status or bullpen_signup as follow-ups, so routing after the call is left to inference.

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

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

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) by disclosing real money movement ($25–$500), the conversion of the full amount to credits plus $10 free, and the two-phase protocol: an initial 402 payment challenge with a retry URL, then an api_key on the paid retry. It even specifies the exact header format (Authorization: Bearer bp_live_…) needed to use the returned credential, which no structured field conveys.

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

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

Front-loaded with what the tool does and the payment mechanism, then the return contract, then pricing — a sensible order with little waste. The inline CLI example and trailing parenthetical are dense but each carries usable information; minor tightening is possible around the two mentions of the retry/return 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?

With no output schema, the description carries full burden and does so: it explains the 402 challenge, the retry URL, the api_key delivery, and how to authenticate. Pricing and credit conversion are covered, leaving nothing an agent needs in order to invoke this 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 baseline is 3, but the description adds meaning the schema does not: the amount is not just a USD number, it becomes credits in full plus a $10 bonus, which materially affects how an agent should choose a value. Other params (company, owner_email) are documented adequately in the schema and correctly not repeated.

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: "Start creating a Bullpen workspace for your principal by paying" — an agent can immediately tell this is a paid signup, not a generic payment call. It is distinguishable from siblings like top_up_credits and credits_status only by inference, since neither is named explicitly.

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

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

Usage is implied rather than stated: "(No API key needed.)" signals this is the entry point before you have credentials, and the 402-retry flow describes the mechanics. However, it never says when NOT to use it versus top_up_credits (existing workspace) or what to do if signup has already happened, so the agent must infer the boundary.

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

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

Annotations cover safety (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds genuinely new context: the transaction happens on an external Stripe checkout page that a human must complete, and it is card-based rather than balance-based. It does not disclose link lifetime, whether credits post only after payment, or what the caller receives on failure, which keeps it below a 5.

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

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

Two short sentences with no filler, and the core mechanism (Stripe link the user opens) is front-loaded before the sibling routing. The idiomatic phrasing 'your person' is slightly ambiguous about who exactly is meant, which is the only friction.

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

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

For a one-parameter tool with no output schema, the description covers the mechanism, the amount bounds, the human-in-the-loop nature, and the sibling alternative. Nothing essential to correct invocation is missing, and return-value detail is not required here since no output schema exists and the artifact (a link) is named inline.

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

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

Schema coverage is 100% and the single parameter already documents 'Amount in USD, 20–10000.' The description merely restates that range in parentheses, adding no new meaning such as currency assumptions, rounding, or whether the amount maps 1:1 to credits. Baseline 3 applies.

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

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

The description states the concrete outcome: a Stripe Checkout link the user opens to add credits by card, with a dollar range. It is clearly distinguishable from siblings like credits_status or top_up_credits. It loses a point only because it is phrased as a noun ('A Stripe Checkout link...') rather than an explicit verb describing what the tool itself does (generate/return a 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?

It names the alternative (top_up_credits) and the condition that selects it ('Agents with a wallet'), and the phrase 'your person opens' signals that this path is human-in-the-loop. It stops short of full exclusions — nothing about what to do if the user has no card, or whether an unpaid link expires — so it is strong but not exhaustive.

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

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

Annotations only say this is not read-only and not destructive; the description goes well beyond them by disclosing the $3/month price with first month charged immediately, that a crew line is provisioned and staffed right away by default, and the admin/manager permission gate. The one material gap is reversibility — it never says whether a purchase can be cancelled, refunded, or released.

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 dense sentence with the price and default behavior front-loaded, and no filler. The nested quoting around for:"me" reads awkwardly enough to risk a momentary parse stumble, but nothing is wasted.

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

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

For a two-parameter, money-spending action with no output schema, the description covers cost, timing of charge, default provisioning consequence, and permissions. Only the post-purchase result (what handle or confirmation comes back) and reversibility are unaddressed.

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

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

Schema coverage is 100%, so the mechanical definitions are already covered, but the description adds real semantics for "for": the default crew line gets a crew member assigned immediately, whereas "me" only changes the person's own caller ID. That consequence-level meaning is not derivable from the enum values alone.

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

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

Opens with a specific verb+resource ("Buy a number") and immediately differentiates itself from the sibling search_numbers, which supplies the e164 input rather than performing the purchase. The cost line and the crew-vs-me distinction make the scope unmistakable.

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

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

States the authorization precondition ("Admin or manager only") and a procedural requirement ("Confirm with your person before buying"), which tells the agent when it may act and what gate to clear first. It stops short of naming an explicit alternative tool to use when the user hasn't picked a number yet, though the e164 schema description points back to search_numbers.

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

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

Annotations only say readOnly=false, openWorld=true, destructive=false; the description adds concrete substance by spelling out that confirming carries out a real outbound call, text, or Salesforce update. That is meaningful beyond the hint flags. It still omits whether confirm is irreversible, whether a cancelled action can be retried, and what the call returns.

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

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

Two short sentences, zero filler, with the action described first and the safety caution second. Nothing repeats the title or the schema.

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

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

For a two-parameter mutation with no output schema, the definition covers what the tool does and the risk profile but leaves gaps an agent would care about: what happens after confirm succeeds, whether cancel is permanent, and whether the call is idempotent. Adequate, not 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?

Schema coverage is 50% (id is documented, the decision enum is not). The description partially compensates by mapping the two enum values to "run" and "drop," but it adds no detail on the id beyond what the schema already says, and no note on what a confirm returns or whether the id becomes invalid afterward.

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?

"Run or drop a pending action Herman proposed" gives a specific verb pair (run/drop) and a specific resource (a pending action), and parenthetically names the action types (call, text, Salesforce update). It is clearly distinct from ask_herman, which proposes actions, but it never explicitly contrasts with send_email/send_text, which could also carry out an outbound action.

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

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

Usage is implied rather than stated: the pending action comes from ask_herman, so this tool applies after a proposal exists. The only explicit guidance is the constraint "Only confirm what your principal actually wants," which is a caution, not a when-to-use/when-not-to-use rule, and no alternative path (e.g. re-proposing via ask_herman) is named.

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 openWorldHint=true and readOnlyHint=false but say nothing about the human-in-the-loop flow; the description usefully states that a link is returned and that the user (not the agent) opens it, plus the two scopes being granted. It omits link lifetime, whether it is single-use, how the agent learns approval succeeded, and whether scopes are fixed or consentable, which matter for an OAuth entry point.

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

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

One economical sentence with no filler, and the key fact (a link the user opens) is front-loaded. The noun-phrase opening is slightly awkward for a tool that performs an action, but nothing is wasted.

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

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

For a zero-parameter, no-output-schema tool the description does cover the essential return (a link) and who consumes it, which is the minimum an agent needs. Gaps remain around what state the integration is in after the user opens the link and how to verify success, likely via a sibling such as onboarding_status, which is never referenced.

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; baseline 4 applies. No misleading parameter hints are present.

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

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

The description names the concrete outcome (a link to approve Google Calendar and Gmail) and the downstream purpose (booking meetings, sending mail), which separates it from sibling connect_salesforce by provider and scope. It stops short of a verb-first statement of what the tool itself does (mint/generate an OAuth link), so the action is inferred rather than stated.

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

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

Usage is only implied through 'for booking meetings and sending mail' — an agent can infer this is the prerequisite step before those actions, but there is no explicit trigger condition, no note that this must precede send_email or calendar work, and no mention of connect_salesforce as the alternative for CRM data.

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

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

Annotations only declare non-read-only, open-world, non-destructive; the description adds the meaningful behavior that a human must open the link and approve, and that the result is every call writing to Salesforce. That human-in-the-loop nature is genuinely new context. It stops short of saying what is returned or how long the link lives.

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

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

Two short sentences with no padding, and the effect (calls write to Salesforce) is front-loaded. But 'A link your person opens' is clumsy and slightly cryptic, costing clarity without saving meaning.

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 zero-param connection tool the description covers who may use it and what enabling it achieves. It omits that the tool returns a URL to be handed to the person, and any expiry/single-use behavior, which an agent needs to relay the link 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies since no parameter semantics are needed.

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 that this produces a link a user opens to authorize Bullpen in Salesforce, so calls write there, which is enough to identify an OAuth-connect action. However, 'A link your person opens' is awkward phrasing and never states the concrete output (a URL/authorization link) or names the sibling connect_google it parallels. Purpose is inferable rather than stated with a clean verb+resource.

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?

'Admin or manager only' gives a real eligibility constraint that the schema and annotations do not carry. There is no guidance on when to call this versus connect_google, or on whether the link is one-time/expires, so usage context 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 readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the mutation and closed-world profile is covered structurally. The description adds lifecycle context but not the consequences an agent would want: whether creating a campaign consumes credits, whether it is reversible, or whether the word "calling" implies any calls are placed immediately. For a create operation with an open question about side effects, this is a modest gap.

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 core action and followed by the workflow. Every clause carries information and nothing 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?

The tool is simple (2 params, 1 required, no nesting) and the workflow is well covered. However, there is no output schema, and the description never indicates that a campaign identifier is returned — which the very next step, import_campaign_contacts, presumably needs. That missing handoff detail is the main completeness gap.

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

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

Schema description coverage is 100%, with both name and goal already documented in the schema (including the goal example). The description adds no meaning beyond that, so the baseline of 3 applies. No enum or format nuance is supplied.

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: "Start a calling campaign." That distinguishes it from siblings like work_campaign (which works an existing campaign) and import_campaign_contacts (which populates one). It stops short of an explicit negative boundary, but the creation scope 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?

Gives a concrete lifecycle: create here, then add contacts via import_campaign_contacts, then run work_campaign. That sequencing is real guidance an agent can act on and prevents out-of-order calls. It does not state exclusions or prerequisites such as required account credits or permissions.

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=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the payload includes recent usage, and a zero balance causes downstream spending tools to fail with a 402. It stops short of describing freshness, currency, or the usage window.

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

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

Two short sentences with no filler, and the primary capability is front-loaded before the failure-mode note. 'Recent usage' is slightly under-specified, but nothing 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 no output schema, the description carries the burden of explaining the return value, and it only gestures at 'balance and recent usage' without stating fields, units, or the usage window. For a simple zero-parameter read this is close to adequate, but the sibling top_up_credits and the 402 condition suggest a remediation path that is never spelled out.

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 of 4 applies. The description correctly implies the call is unfiltered and account-scoped rather than parameterized.

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

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

The description names a specific resource (prepaid credit balance) plus a secondary payload (recent usage), which is enough for an agent to know this is a read of account credit state. It is distinguishable from top_up_credits, which mutates the balance, though it never names that sibling explicitly.

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

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

The sentence 'Spending tools return a 402 error at zero' implies the when-to-use case (check before calling send_email, send_text, create_campaign, etc.), but the inference is left to the agent rather than stated. There is no explicit guidance on when not to call it or on routing to top_up_credits when the balance is low.

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

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

The annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description's main added value is naming the returned fields (names, main phone lines, websites), which matters because there is no output schema. It says nothing about result caps, cost/credit implications, or data freshness, which are relevant for a lead-sourcing lookup.

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: purpose plus example first, return fields second. Everything is front-loaded and the total length is proportionate to a simple two-parameter lookup.

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 low-complexity search with full schema coverage and no output schema, the description covers purpose, example input shape, and return contents. Minor gaps remain around result limits and whether the call consumes credits, but nothing essential 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 100%, so both parameters are already documented ('Who you're looking for, with place' and 'Max results, default 20'). The description's example query reinforces the format but adds no syntax or constraint details beyond the schema, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('Search for companies to sell to') and anchors it with a concrete example query, which distinguishes it from research_company and watch_companies without opening any schema.

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

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

The phrase 'to sell to' implies prospecting usage, but the description never states when to use this instead of siblings like research_company or watch_companies, nor any exclusions or prerequisites. Usage is inferable but not spelled out.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the description only needs to add freshness/scope context. It gestures at "live and recent" but never defines the time window, whether it polls or snapshots, or what a caller gains from this versus other presence tools.

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?

Six words with no filler, which is commendably tight, but the brevity comes at the cost of substance rather than being appropriately sized. There is no front-loaded statement of what is returned or when to call it.

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

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

With no output schema and a single readOnly annotation, the description carries the full burden of explaining what comes back. It does not say whether the result is a list of crew members, their statuses, or call records, nor how "recent" is bounded, which leaves the agent guessing at the return shape.

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 effectively complete, so there is no parameter meaning to add. Baseline 4 applies; nothing in the description misleads about 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?

"Live and recent crew calls" is a noun fragment with no verb, and the term "calls" is ambiguous (phone calls? decisions? who is available?). The title "Who's on the floor" hints at presence/availability, but the description never confirms what resource is actually being read, so an agent cannot confidently distinguish it from siblings like whoami or get_a_human.

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

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

There is no when-to-use guidance at all. The description does not mention the alternative siblings (whoami, get_a_human, ask_herman) or the condition under which checking floor state is preferable, leaving selection entirely 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 only declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the description carries real extra weight: it discloses the cost model ($0.30 per crew minute, no extra charge once a person is reached) and a consent/legal restriction on which numbers may be dialed. It stops short of stating failure behavior—what happens or what is billed if no human is reached, whether calls are recorded, or expected hold duration.

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

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

Two sentences, the mechanism front-loaded before the cost and consent caveats, with almost no filler. Minor friction from the phrase 'the key's owner,' which is not defined anywhere in the definition.

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

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

There is no output schema, so the description must convey what a call yields; it explains the connection flow but not what the tool returns (call identifier, status, transcript, success/failure signal) or timing expectations. For an open-world, credit-spending action that is a meaningful gap.

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

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

Schema coverage is 100%, so all three parameters are already documented inline, establishing a baseline of 3. The description adds only indirect meaning—that 'to' is the company line being navigated and that a 'target' person is who the crew asks for—without new formatting or edge-case guidance beyond the schema.

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

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

The description names a concrete actor and action chain: 'A crew member dials the number, works the phone menu, hold and AI receptionist until a real person answers, then connects the key's owner into the live call.' That is far more specific than a restated title and clearly separates it from text/email siblings like send_text or send_email.

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 eligibility constraints ('Company lines only unless the callee gave written consent'), which implicitly bounds when the tool may be used, but it never states when to prefer it over send_text, send_email, or knock, nor what to do if the line is a personal number.

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 readOnlyHint the description adds genuinely useful behavior: the recording link is signed, MP3 format, and expires after one hour, and speaker attribution includes handoff participants. These are details an agent cannot infer from annotations or schema and materially affect how it should handle the 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?

A single dense sentence with the payload front-loaded and zero filler. It is slightly run-on with the nested parenthetical, but every clause carries information an 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?

No output schema exists, so the description carries the return-value burden and does so fully: both transcript forms, summary, outcome, and recording format with expiry. Combined with 100% parameter coverage, an agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description restates the id guidance rather than adding format or edge-case detail. The optional `recording` toggle is only implied by the mention of a signed link, which the schema already covers, so baseline 3 applies.

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

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

Opens with a specific verb+resource and scope ("One call in full") and enumerates exactly what is returned: transcript text, timed speaker lines, summary, outcome, recording link. It is immediately distinguishable from list_calls, the sibling it names.

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?

"Pass an id or call SID from list_calls" establishes the correct upstream workflow and implicitly positions this as the single-call counterpart to list_calls. It stops short of explicit when-not guidance (e.g., that bulk retrieval requires list_calls), so it is clear context but not a full routing rule.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds non-obvious behavioral context: that outbound messaging is gated on acceptance of this agreement. It does not describe formatting or how the version field is presented, but the added gating information is the substantive piece.

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

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

Two short sentences with no filler, and the gating consequence is front-loaded rather than buried. Every clause adds decision-relevant information.

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

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

For a zero-parameter read tool with no output schema, the description covers both what comes back (the agreement and its version) and the workflow position relative to accept_outbound_agreement. Nothing an agent needs in order to call it correctly is missing.

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

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

The tool takes zero parameters, so there is no parameter semantics to document and the baseline of 4 applies. The description correctly avoids inventing argument behavior.

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

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

The description names a specific resource (the Outbound Compliance Agreement) and states what is returned ('and its version'), which lets an agent distinguish it from the sibling accept_outbound_agreement. The retrieval verb itself is only carried by the title ('Read the...'), not the description body, so it falls just short of a self-contained 5.

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

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

It states exactly when to call it ('Show it to your person before accept_outbound_agreement') and names the specific sibling that follows it. It also explains the consequence of skipping it — calls and texts stay locked until acceptance — which routes the agent unambiguously.

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 is a non-read-only, non-destructive, closed-world mutation. The description usefully adds that the operation applies to *every* free phone line rather than one line, which is real scope information the annotations don't carry. However, it says nothing about cost/credit consumption (notable given sibling tools buy_credits and credits_status), idempotency, or what happens to lines already occupied by a crew member.

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 its effect, followed by the prerequisite. Very little waste; only the '(name, voice, role)' parenthetical is questionable overhead given there are no matching parameters.

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 zero-parameter tool with no output schema, the definition covers what it does and when to run it. It leaves out operationally relevant facts: whether hiring consumes credits, whether it is idempotent, and what the caller can expect on failure or partial success across multiple lines.

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, which normally sets a baseline of 4. But the parenthetical '(name, voice, role)' implies configurable inputs that do not exist in the empty schema, creating ambiguity about how a crew member's identity is specified. That ambiguity pulls the score down from the 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?

The description gives a concrete verb and resource: 'Put an AI crew member ... on every free phone line'. It also states the effect's purpose ('so the crew can dial'), which distinguishes it from setup tools like buy_number. It doesn't name a sibling explicitly, so it falls short of a 5.

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

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

'Run after a number is bought' gives a clear ordering prerequisite that maps to buy_number. There is no guidance on when NOT to run it, or what happens if the crew is already hired, so it stops short of explicit when/when-not/alternatives.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the concrete CSV header contract, but omits important import behavior: whether rows append or replace, how duplicates are handled, and whether partial/invalid rows abort the whole import. Those gaps keep it at a 3.

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 carrying the action and the format contract with no filler. Nothing in it could be removed without losing information.

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

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

For a two-parameter import tool the input contract is adequately covered, but with no output schema the description should say what a successful import reports (counts, per-row errors) and how failures behave. The duplicate and error semantics remain undefined.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema's terse 'CSV text.' by naming the exact header row and column order (company, phone, name, title, email). That is genuinely new meaning an agent needs to build a valid payload.

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 ('add contacts to a campaign') plus the transport format ('from CSV text'), which separates it from create_campaign and work_campaign. It stops short of explicitly naming a sibling or scope boundary, but the action 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 phrasing 'add contacts to a campaign' – there is no statement of when to prefer this over create_campaign or work_campaign, nor any prerequisite (e.g. campaign must exist, contacts must be new). An agent can infer the intent but gets no routing guidance.

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

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

Annotations already establish the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the description only needed to add context. It does: it discloses that an external email with a sign-in link is dispatched and that an admin-only constraint governs admin-role invitations — both facts absent from 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?

A single front-loaded sentence with the invitation mechanism first and the role constraints second — every clause carries information. The role enumeration mildly duplicates the schema enum, 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?

For a two-parameter mutation with no output schema, the description covers side effects and permissions well. But role is optional in the schema and the description never says what happens if it is omitted (default role, or invite with no role), which is a meaningful gap for an agent deciding what to send.

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%, with the role parameter lacking any schema description, so the description carries real weight here. It enumerates the valid roles and adds the non-obvious authorization rule (only admins may invite admins), which the enum alone cannot convey; the email parameter still gets no format or normalization detail.

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 ("Invite someone to the workspace by email") plus the observable outcome (a sign-in link landing on the join page), which is far more informative than the title alone. It does not, however, differentiate itself from plausible siblings such as hire_crew or bullpen_signup, leaving the agent to infer which invitation path applies.

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 rather than stated — the tool is for adding a teammate to the current workspace, and the parenthetical "only admins invite admins" supplies a genuine permission precondition. There is no explicit when-not guidance or routing to alternatives like hire_crew, so the agent must guess at the boundary.

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 three behaviors an agent could not infer: the action consumes credits, it is rate-limited to once per week per company, and it only works during business hours. It does not say whether a human actually answers or a voicemail is left, nor what a failed attempt looks like, which are the remaining meaningful gaps.

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 no waste: the action first, then the operating constraints, then the cost. Each sentence carries distinct information the agent needs, and the front-loaded verb makes the tool's identity immediate.

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 four-parameter, non-destructive but credit-consuming outbound action with no output schema, the description covers cost, timing, and rate limits – the facts most likely to cause a mis-invocation. It stops short of describing outcomes (connection vs voicemail, error conditions) or what 'principal' refers to, leaving a small but real gap.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema; the baseline is 3. The description adds modest meaning – "short hello" constrains the note content and "pointing to your principal" hints at what target is for – but it introduces no format or syntax 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?

"Reach a human at a company's main line and leave a short hello pointing to your principal" states a concrete verb (call/reach) and resource (company main line) and implies a voice channel, which distinguishes it from siblings like send_email and send_text without naming them. It is not tautological, but it never explicitly contrasts itself with ask_herman or get_a_human.

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 supplies operating constraints – business hours only, once per week per company – which implicitly tell the agent when this is permissible. It does not say when to prefer this over the email/text siblings or what prerequisites (campaign, credits available) must hold, so the when-to-use guidance remains 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?

Annotations already declare readOnlyHint and openWorldHint=false, so safety is covered; the description adds ordering (newest first), a concrete field manifest, and a role-based visibility rule that materially affects how results should be interpreted. It stops short of mentioning pagination limits beyond the schema's limit cap or default behavior when results are truncated.

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

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

Two sentences: the first front-loads the resource and ordering then lists fields; the second covers access scope. The field enumeration is dense but each item tells the agent what it can rely on, so little is wasted.

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

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

With no output schema, the description carries the return-value burden and does so by naming every field, including derived booleans for transcript and recording availability. Combined with fully documented parameters and annotations covering read-only safety, an agent has enough to call this correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents 'to', 'limit', and 'since'. The description adds no parameter-level meaning (e.g. whether 'to' matches either direction is only in the schema), so baseline 3 applies.

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

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

The description makes clear this returns a list of recent calls with newest first, and enumerates the returned fields, so an agent knows exactly what resource it gets. It does not name a verb ('list') explicitly nor differentiate itself from get_call_transcript, which is the natural follow-up when a transcript exists.

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

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

There is no when-to-use guidance, no exclusions, and no named alternative — an agent gets no signal about when to call this versus get_call_transcript or other call-related siblings. The permission note ('Reps see their own calls; managers and admins see all') explains result scope but is not usage 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=true and openWorldHint=false, so the safety profile is covered. The description adds that pending invites include their links, which is genuinely useful output context, but says nothing about scope, permissions, who can see it, or what 'Herman on' signifies.

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

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

It is short and front-loaded, but it is a sentence fragment rather than a description, and the nested parenthetical with 'Herman on' is ambiguous enough that compactness costs clarity.

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

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

With no output schema, the description is the only source of return-value information, and it does list the main data points. However, for a zero-argument, zero-output-schema tool it should fully describe the response shape; unspecified items like invite status or member identity fields remain 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?

The tool takes zero parameters, so the baseline is 4. The parentheticals describe returned fields rather than inputs, which is appropriate here and adds some value in the absence of an output schema.

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

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

The description is a noun phrase with no verb; it states what data comes back (members, pending invites) rather than what the tool does. The parenthetical 'role, whether their mobile is set, Herman on' is specific about returned fields, but 'Herman on' is cryptic and nothing distinguishes it from the sibling invite_teammate.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. The agent must infer that this is the read counterpart to invite_teammate purely from the name and sibling list.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description doesn't need to re-establish safety. It does add useful behavioral detail beyond them: the response is ordered by execution sequence and each entry carries the tool or link that resolves it, which is meaningful for a tool with no output schema. Rate limits or behavior for a partially configured workspace are not covered.

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

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

Purpose is front-loaded in the first clause, and the trailing 'Start here after signing up' lands the routing advice. The long parenthetical enumerating checklist categories adds real information about scope but is bulky and slightly noisy ('Herman', 'your mobile' alongside 'phone number' are not obviously distinct).

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 zero-parameter, no-output-schema read tool this is close to sufficient: it conveys what comes back (ordered checklist with resolving tool/link per item) and where it fits in the flow. It could say more about what a fully-configured workspace returns, but nothing essential to 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?

The tool takes zero parameters, so the baseline of 4 applies and there is no parameter ambiguity to resolve. The description correctly spends its words on the return content instead of inventing 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 concrete verb+resource: a checklist of what the workspace still needs before every feature works. The enumerated items (compliance agreement, phone number, crew, credits, Salesforce, Google, texting) make it unmistakable against siblings like credits_status or whoami, which report a single state rather than the full setup path.

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

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

'Start here after signing up' gives clear entry-point guidance for new workspaces and implies this is the first call before the individual setup tools. It stops short of saying when not to call it (e.g. once setup is complete, or when only one specific gap needs checking via credits_status/whoami), so no explicit exclusion is offered.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful context with '(No API key needed.)' and the note that API keys can be revoked at the api_keys page, but it says nothing about whether the link is shareable, expiring, or scoped to the caller's org.

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 single semicolon-delimited run-on is hard to scan and repeats 'floor' twice within a few lines. The list is dense but each gloss is short, so it is wasteful in structure rather than in 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?

For a one-parameter link generator with no output schema, the description covers the full enum domain and the auth expectation, which is most of what an agent needs. Remaining gaps — link lifetime, whether it is user-scoped — are minor for this tool class.

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

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

Schema description coverage is 0%, so the description must carry the load — and it does, giving a parenthetical gloss for every one of the nine enum values (e.g. human_line = 'your mobile and live bridge calls', billing = 'credits, billing and the Outbound Compliance Agreement'). Only the redundant re-explanation of 'floor' and the lack of URL-format detail keep it from a 5.

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

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

The description opens by saying it produces 'A link your person can open' and then enumerates the nine page targets, so an agent can tell this returns a URL for a specific Bullpen surface rather than data about it. The verb is implied rather than stated (the title carries 'Get a link'), and it does not explicitly contrast itself with siblings like floor_state or whoami, keeping it below a 5.

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

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

There is no statement of when to call this versus alternatives — notably floor_state for live call data or whoami for identity. The only usage-adjacent remark is a duplicated note that 'floor' is the live floor to watch calls, which hints at intent but is not routing guidance.

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

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

Annotations declare readOnlyHint=false with destructiveHint=false and openWorldHint=false, meaning this performs some non-trivial action, but the description says nothing about cost, latency, side effects, or whether research results are cached or persisted. With no annotation coverage of those traits, the description carries the burden and does not meet 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?

It is a single short fragment with no wasted words, but the terseness is under-specification rather than efficiency and there is no front-loaded statement of what the tool actually does. The clause order puts the outcome before the action, which reads awkwardly.

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

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

There is no output schema, so the description must explain what 'research' returns; 'who to ask for' gestures at contacts but does not say whether that is names, emails, roles, or a ranked list. For a single-parameter tool this is minimal, and the missing return shape leaves an agent unable to anticipate results.

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 id parameter is documented as coming from find_companies, which the description repeats rather than extends. Baseline 3 applies since the schema already does the work and no additional meaning (format, validity, failure modes for bad ids) is added.

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 is a sentence fragment with no verb, but it does narrow the vague title 'Research a company' to a concrete outcome: returning the right people to contact at a company, sourced from find_companies. It distinguishes itself from find_companies only by referencing it as the id source, not by explaining how the two tools differ in what they return.

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 saying the id comes from find_companies, it suggests a find-then-research chaining pattern. There is no explicit statement of when to call this versus ask_brain, ask_herman, or knock, 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=true and openWorldHint=false, so safety is covered. The description adds only 'available' (not already taken) and the opaque phrase 'for the crew's lines', which communicates nothing actionable about result volume, ordering, or what an empty result means.

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

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

It is short with no padding, but it is a single noun-phrase fragment rather than a front-loaded statement of action. 'For the crew's lines' occupies space without conveying information.

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

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

For a simple one-parameter read tool with annotations this could be near-complete, but the missing hand-off to buy_number leaves the agent without the next step. Nothing explains what the returned numbers look like or whether they can be reserved.

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

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

Schema coverage is 100% and the schema already documents the 3-digit area code with an example. The description adds only the US-only scoping and the 'available' qualifier, so baseline 3 applies.

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

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

The fragment names the resource (US phone numbers) and the filter (by area code), so an agent can infer it searches availability. But there is no verb and no mention of the obvious sibling buy_number, so the boundary between searching and purchasing is left to inference.

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

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

There is no when-to-use guidance and no mention of buy_number, accept_outbound_agreement, or any prerequisite for acquiring a number. The agent must guess whether this tool merely lists candidates or is the acquisition step.

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, openWorldHint=true and destructiveHint=false, so the safety profile is largely covered. The description contributes one genuinely useful fact — that mail originates from the workspace's agent inbox, identifying the sender — but says nothing about irreversibility of sends, rate limits, delivery behavior, or how the result is reported. For an external outbound action, that is a substantial gap.

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?

Brevity here is under-specification rather than conciseness: a single verbless fragment that omits the core action. There is nothing to trim, but there is also nothing front-loaded because almost no content exists.

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 is simple (4 params, no nesting, no output schema), but as an outbound write with an open-world hint, an agent still needs to know the sender identity, whether sends are final, and roughly what comes back. Only the sender-inbox detail is supplied, so the definition is incomplete relative to even this modest complexity.

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 to, subject, text and cc all documented inline, so the baseline of 3 applies. The description adds no formatting constraints (HTML vs plain text), address syntax, or cc semantics beyond what the schema already supplies.

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 is a noun phrase, 'Email from the workspace's agent inbox,' that never states an action verb; the only signal that this sends rather than reads mail comes from the tool name and title. It restates the title rather than defining the operation, and gives no hint of what distinguishes it from siblings like send_text.

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

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

There is no when-to-use guidance, no preconditions, and no mention of alternatives such as send_text or get_a_human. An agent must infer entirely from the name that this is for outbound email.

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

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

The annotations already flag this as a non-read-only, open-world, non-destructive action, but the description adds genuinely new context: messages are sent from the workspace's line, opt-outs are honored (so some sends may not deliver), and the call consumes credits. Missing are rate-limit behavior, error handling, and what a send failure looks like.

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 clipped clauses, front-loaded with what the tool does and followed by the two facts an agent most needs (opt-out compliance and cost). Nothing is padded, though the telegraphic style borders on under-specification.

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

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

For a two-parameter mutation with no output schema, the description covers the essentials an agent needs to decide and invoke, but it never says what the call returns (message ID, delivery status) or what happens if the recipient has opted out. Those gaps matter for a cost-bearing send action.

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

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

Schema coverage is 100%, with both parameters documented ('E.164 number' and 'Message'), so the schema does the heavy lifting. The description adds no further meaning about formatting, length limits, or multi-recipient behavior, 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?

"Text from the workspace's line" gives a concrete verb (text/send) and resource (SMS from the workspace line), which is specific enough to separate it from email or in-app messaging siblings. It doesn't explicitly contrast itself with the other outbound tools such as the sibling send tool, so it stops short of full differentiation.

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

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

There is no statement of when to use this versus alternatives (e.g., email or the other outbound messaging tools), and no prerequisite or precondition guidance beyond the implicit need for a recipient and body. Usage must be inferred from the tool name alone.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false. The description adds real behavior beyond that: the number's downstream effect (it is what rings on human handoff), the default ownership scope, and the manager-level authorization path. It doesn't cover validation failures or whether an existing number is overwritten, which keeps it off 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?

Two short sentences, zero filler. The core effect of the tool is front-loaded, and the ownership/permission detail follows as the second clause.

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

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

For a two-parameter tool with full schema coverage, annotations, and no output schema, the description covers purpose, default scope, authorization, and the sibling reference that supplies user_id. The only gap is what the call does to any previously set number, which an agent could reasonably want to know before calling.

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 format details (E.164 or 10-digit US) are already documented and the baseline is 3. The description adds meaning the schema lacks: user_id carries an authorization implication (managers only) and a provenance hint (from list_team), which changes how an agent should populate 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?

States a specific verb and resource ('Set the mobile') and immediately clarifies the effect — it's the number that rings when the crew hands off to a human via get_a_human. That distinguishes it from number-related siblings like buy_number and search_numbers without the agent needing to open another 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 context for the optional parameter: default scope is the caller's own number, and managers can target a teammate using user_id sourced from list_team. It doesn't state exclusions or failure conditions (e.g., what happens if the caller isn't a manager), so it stops short of 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 already indicate this is a non-read-only, open-world, non-destructive operation. The description adds meaningful behavior beyond that: it returns a 402 challenge and a payment URL, and requires retrying with the client using the key header. It stops short of explaining post-payment behavior or failure cases.

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

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

The description is two compact sentences and front-loads the action and range before the payment-flow details. Every phrase contributes useful information.

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

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

For a one-parameter tool with no output schema, the description adequately explains the key return behavior and retry flow. It could be slightly more complete by mentioning when the top-up is recommended or what happens after payment succeeds.

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

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

Schema coverage is 100%, and the schema already documents that amount is USD and bounded 5–500. The description repeats the same range without adding syntax, formatting, or edge-case guidance, so baseline 3 is appropriate.

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

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

The description states a specific action and resource: starting an MPP credit top-up with a defined USD range. It is clear what the tool does, though it does not explicitly differentiate itself from the related credits_status 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?

The description implies usage context by describing the pay-and-retry flow with an MPP client and the X-Bullpen-Key header. However, it does not explicitly say when to use this versus checking credits_status, nor does it state prerequisites such as already having an MPP client or key.

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

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

The annotations already establish that this is a non-read-only, non-destructive, closed-world operation. The description adds useful scope by saying it is per member and that it enables ask_herman, but it does not disclose idempotency, reversibility, permission requirements, or behavior when the member already has Herman switched on. That is a meaningful omission for a mutation tool, though the annotations carry part of the burden.

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

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

It is a single sentence with no filler, and the dependency on ask_herman is front-loaded with the action. Every clause contributes to understanding what the tool does and why it exists. There is no unnecessary repetition or rambling.

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

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

For a zero-parameter activation toggle with annotations covering the safety profile and no output schema, the description supplies the key context: per-member scope and the link to ask_herman. It is nearly complete, but it could clarify whether switching on is idempotent and what 'on' persists for the member.

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

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

The tool has zero parameters and a 100% schema coverage baseline, so there is no parameter syntax or meaning for the description to add. The description correctly avoids inventing parameter details and does not contradict the empty schema. Baseline 4 is appropriate for a parameterless 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?

The description uses a specific verb and named entity: 'Switch Herman on' and ties the effect to making 'ask_herman' work. That tells an agent what operation is being performed and which sibling depends on it. The main gap is that 'Herman' is not defined and the description does not explicitly distinguish this toggle from related tools such as confirm_herman_action.

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 phrase 'so ask_herman works' implies this should be used when ask_herman is not yet available or needs activation for the member. However, there is no explicit when-to-use condition, no when-not-to-use guidance, and no mention of what to do if Herman is already on. Usage is inferable but not fully specified.

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 is a non-read-only but non-destructive, closed-world write. The description adds genuine value by disclosing that adding a company enrolls it in continuous scanning for buying and risk signals — a persistent side effect. It omits what happens to duplicate entries, whether companies can be removed, and whether this consumes credits.

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

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

One sentence, front-loaded with the action and destination, with the scanning rationale in a subordinate clause. Nothing extraneous.

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

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

For a one-parameter tool with full schema coverage, annotations, and no output schema, the description covers the action and its persistent effect. Minor gaps are duplicate handling and whether the scan consumes credits, both relevant to a monitoring-enrollment 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 description coverage is 100%, so the baseline is 3. The description's plural framing ('companies') corroborates batch input, and the schema already specifies comma or newline separation, leaving little unaddressed.

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 ('Add') and resource ('companies to Social Intel') plus the downstream effect ('scans them for buying and risk signals'). This is enough to distinguish it from siblings like find_companies or research_company, though it never explicitly contrasts with them.

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

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

Usage is implied: add companies when you want ongoing signal monitoring rather than a one-off lookup. There is no explicit when-to-use/when-not guidance, no mention of the alternative siblings (research_company, find_companies), and no note on prerequisites or whether re-adding duplicates is safe.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false). The description adds the key behavioral fact beyond that: the identity returned is scoped to the calling API key, not a parameterized user. It does not say anything about auth failure behavior or whether the result is cached/session-scoped, so the addition is modest.

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

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

A single front-loaded sentence with no filler. It is slightly under-specified as prose (no verb), which costs a point, but nothing is wasted.

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

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

With no output schema, the description carries the burden of telling the agent what comes back. It enumerates the fields at a high level (workspace, member, role), which is helpful, but omits identifiers, nesting, or the response shape, leaving an agent to discover the actual payload at call time. Adequate but not fully complete for a tool with no output contract.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly frames that the subject is implicit (the API key), which is the one semantic point that matters for a no-arg call.

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

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

The description names the resource ('workspace, member and role this API key acts as'), making it clear this is an identity/credential introspection tool distinct from siblings like credits_status or bullpen_about. It is a noun phrase rather than a verb+resource statement, so the action ('return the current identity') must be inferred, but the intended output 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 implied rather than stated: an agent can infer this is the call to make when it needs to know which workspace/member an API key belongs to. There is no explicit when-to-use framing, no mention of whether it requires a valid key or what happens on an unauthenticated call, and no pointer to alternatives.

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

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

Annotations already declare a non-read-only, open-world, non-destructive operation, so the safety profile is covered. The description adds genuine value beyond them by disclosing the cost side effect with 'Spends credits'. However, it says nothing about whether the work is asynchronous, whether it can be re-run on the same campaign, what happens to already-worked contacts, or whether a confirmation step is expected.

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

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

Two short sentences, front-loaded with the action and followed immediately by the credit cost. Nothing is padded, though the phrasing is terse enough that a little more structure could have carried prerequisites without bloat.

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, open-world action with no output schema, the definition covers what it does and that it costs credits, which is the essential minimum given annotations handle safety. It falls short on execution semantics an agent would want before spending credits: is it immediate or background, is it repeatable, and does it require a confirmation or sufficient balance first.

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 one parameter at 100% schema description coverage, the schema already tells the agent that 'id' is the campaign id. The description only indirectly frames the id as the campaign whose contacts get worked, adding marginal meaning. Baseline 3 applies.

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

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

The description states a specific action on a specific resource: send the crew to work a campaign's contacts. That clearly distinguishes it from siblings like create_campaign and import_campaign_contacts, which set campaigns up rather than execute them. The only weakness is the internal jargon 'crew', which an agent must infer means the sending/outreach system.

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 guidance and no named alternatives. The description implies the campaign must already exist with contacts (otherwise there is nothing to work), but the prerequisites and the choice versus per-contact tools like knock or send_email are left entirely to inference.

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