Deeplead

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

Annotations mark this non-read-only but non-destructive; the description corroborates with the saveToContacts write side effect and goes further by disclosing the credit model (1 credit per business with email/phone, 0.5 without) and page size. It omits auth requirements and whether the contacts write is reversible.

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

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

Four short sentences, each front-loaded with the most decision-relevant facts (source, scale, cost, side effect). The '30 per page' fact is duplicated in the schema, a minor redundancy.

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

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

With an output schema present, return values need no explanation, and the description supplies the cost model, pagination, and contacts side effect. It stops short of noting the 100-page cap or any authentication/credit-balance prerequisites.

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 10 parameters are documented in the schema itself, establishing a baseline of 3. The description adds only the credit distinction tied to email/phone presence and the 30-per-page limit, both of which largely restate schema details.

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 (Search) plus resource (local businesses from Google Business Profiles) and quantifies the corpus (23M+). It is clearly distinguishable from siblings like organizations_search and persons_search, which cover different entity types.

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

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

Usage is implied by the resource description, but there is no explicit when-to-use or when-not guidance and no alternatives named among the sibling search tools. An agent must infer that this is the local-business search rather than organizations_search.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds genuinely new behavioral context: the deletion is guarded and will not proceed for ideas tied to a live or launched campaign. It does not state irreversibility or what error/return occurs when the guard trips, though the output schema covers 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 with the core action and precondition front-loaded, and the exception second. Tight and waste-free, though the second clause is slightly compressed.

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

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

With annotations carrying the destructive profile, an output schema, and a fully documented single parameter, the description covers nearly everything needed. The remaining gap is not naming the tool to use on the archive path.

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

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

Only one parameter, with 100% schema coverage and an inline description pointing at campaign_ideas_list as the source. The description adds nothing about ideaId, so the baseline 3 applies.

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

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

States a specific verb and resource (delete a campaign idea) plus a hard precondition (must have no campaign), which is more than the name conveys. It does not name the sibling tool that performs the suggested archive alternative, so sibling routing is only implicit.

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

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

Explicitly gives the use condition (idea with no campaign) and a when-not condition (idea that launched or is launching a campaign), pointing to an alternative action. The alternative is described as an action ('archive its campaign') rather than a tool name such as campaigns_set_status, leaving one inference 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=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the description needs to add little. It does add that the response includes the draft, audience size and example emails, but that overlaps with the output schema. Nothing is said about behavior if the ideaId is unknown or about freshness of audience size.

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

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

It is one short sentence with no filler and the scoping word 'One' is front-loaded. But it is a fragment that duplicates the title exactly, so brevity comes at the cost of information rather than from efficiency.

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 one required parameter at 100% schema coverage, an output schema present, and rich annotations, the description only needs to say what the tool returns and for which record. It does both, so it is sufficient for correct invocation even though routing guidance is thin.

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

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

Schema coverage is 100% and the single parameter's description already tells the agent to obtain ideaId from campaign_ideas_list. The tool description adds no further syntax or semantics, so the baseline 3 applies — the schema does all the work here.

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

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

Tautological: description restates name/title.

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

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

There is no guidance on when to call this versus campaign_ideas_list, campaign_ideas_suggest, or campaigns_get. The only hint is the singular 'One', which an agent must infer on its own.

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

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

Annotations only tell us it is a non-destructive, non-open-world write. The description adds genuinely non-obvious behavior: it returns immediately ('Answers at once') while the work proceeds in the background, and progress is observable by re-reading campaign_ideas_list ('launching' then 'launched'). That asynchronous status model is the key thing an agent needs and isn't in the annotations.

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

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

Three short sentences with the action front-loaded and the async/status behavior following. No filler, though the phrasing 'Each idea shows launching... then launched' is slightly awkward and could be tightened without losing 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?

An output schema exists, so return values needn't be described, and the status lifecycle is covered. Still missing for a mutating batch operation: partial-failure semantics, idempotency/duplicate handling, and any permission prerequisites. These are meaningful gaps for a tool that creates and activates campaigns.

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 0% at the top level, so the description must compensate. It does convey that the parameter is a batch ('each idea') and that ids originate from campaign_ideas_list, but it never mentions the 20-item cap or what happens with invalid/duplicate ids. Partial compensation only.

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 compound action: draft each idea, create its campaign, and activate it. That distinguishes it from campaigns_create or campaign_ideas_get, though it doesn't explicitly contrast with those siblings. The verb+resource is specific enough that an agent knows what calling it accomplishes.

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 tool consumes ideaIds from campaign_ideas_list, so the agent can infer it's a follow-up to browsing ideas. There is no explicit 'use this when' or any exclusion (e.g., when to use campaigns_create directly instead). Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered; the description adds genuine extra context by disclosing that this is a polling endpoint and naming the state conditions under which polling is warranted. The only gap is that the referenced state names ("suggesting", "drafting", "launching") are not defined or mapped to returned fields.

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

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

Two short sentences, front-loaded with the purpose before the polling advice, with no filler. The phrasing "how far each got" is informal and forces the agent to infer that it means idea status/progress, a small clarity cost.

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

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

An output schema exists, so return values need not be explained, and with no parameters the surface area is small. The definition covers purpose and polling behavior adequately; the one omission is any hint about result volume or ordering when many ideas are returned.

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 for the description to compensate for; the baseline for a no-parameter tool applies. The description adds nothing misleading 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?

"List your campaign ideas and how far each got" names a specific verb (List) and resource (campaign ideas) plus the returned status dimension, which cleanly separates it from campaign_ideas_get (single item) among the siblings. It stops short of explicitly naming that sibling, so the differentiation is implied by the plural/list phrasing 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?

It gives concrete operational guidance: poll roughly once a minute, and only while "suggesting is true or an idea is drafting or launching." That tells the agent when to call and when to keep calling, but there is no guidance on when to prefer campaign_ideas_get for a single idea or what to do when no ideas exist.

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

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

Beyond the annotations, the description discloses a real side effect: on a launched idea, recipients not yet contacted who no longer fit are removed, and removedRecipients counts them. That is valuable context the structured fields do not provide, though there is mild tension with destructiveHint=false since data (recipients) is dropped.

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

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

Two tight sentences with the core action front-loaded and the side-effect detail appended. Nothing is wasted and no restating of the title or name.

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

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

An output schema exists so return values need not be explained, and the removedRecipients mention is a helpful extra. However, the undocumented 'exclude' semantics and the undefined category value format leave an agent guessing on two of three required parameters.

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

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

Schema coverage is only 33%, and only ideaId is documented ('ideaId from campaign_ideas_list'). The 'exclude' parameter is left entirely unexplained in both schema and description, leaving ambiguous whether it is categories to exclude or recipients to skip, and no format is given for category strings.

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 ('Set') and resource ('Google Maps categories a Maps idea reaches'), which clearly distinguishes this from sibling campaign_ideas_set_radius and campaign_ideas_suggest. It states exactly what the operation changes, though it never explicitly names the nearest alternative it replaces.

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 hints that behavior differs for launched ideas (recipient removal), which implies a lifecycle context, but it never states when to call this versus set_radius or suggest, nor any preconditions such as whether the idea must exist or be in a given state. Usage must be inferred.

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

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

Adds real value beyond the annotations: it discloses that on an already launched idea, uncontacted recipients outside the new radius are removed, and that the response field removedRecipients counts them. That side effect is not derivable from destructiveHint=false and is exactly the kind of consequence an agent needs before writing. It stops short of saying what happens on a draft idea or whether the removal is reversible.

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

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

Two sentences, zero filler, and the core purpose is front-loaded ahead of the conditional side-effect detail. Nothing could be cut without losing information.

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

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

An output schema exists, so return values need no explanation, and the description still calls out the one non-obvious response field. For a 2-required-parameter setter this is nearly complete; the gaps are the valid radius range and the draft-vs-launched behavioral split.

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%: ideaId is documented in-schema (including the useful 'from campaign_ideas_list' cross-reference) while radiusMiles has no inline description. The description supplies the meaning of the radius (distance from home city) but omits the 5–100 mile bounds the schema enforces, so it neither fully compensates nor is redundant.

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 ('set') and a specific resource/attribute ('how many miles around your home city a Maps idea reaches'), which clearly distinguishes it from generic campaign tools. It implies scope ('Maps idea') but never names set_audience as the neighboring configurator, so sibling differentiation is only partial.

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

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

Usage is implied rather than stated: the reader infers this applies to Maps-type ideas and that behavior differs pre- vs post-launch. There is no explicit when-to-use, when-not-to-use, or 'use campaign_ideas_set_audience instead for X' guidance against the several adjacent campaign_ideas_* siblings.

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

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

Discloses two things the annotations do not: the call is synchronous ('Answers at once') and it overwrites every idea not yet launched, which is a genuine side effect. It also states the operation is free, which matters given the sibling credits_get. The overwrite behavior is arguably stronger than destructiveHint=false implies, so the agent would otherwise be under-warned — the description closes that 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?

Three short sentences, purpose first, then cost/latency, then the side effect, then the parameter variant. No filler; every clause carries an operational fact the agent needs.

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

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

With an output schema present the description needn't document return values, and it covers what matters for this 1-param, zero-required tool: cost, timing, where results appear, and the overwrite behavior. Nothing an agent needs in order to call it safely is missing.

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

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

Schema coverage is 100% and the schema already gives an example, so the baseline is 3. The description exceeds it by explaining the semantic difference between omitting segment (profile-based ideas, which replaces existing ideas) and supplying it ('adds ideas for that audience instead') — a distinction the schema cannot express.

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 ('Suggest campaign ideas') plus the source of truth for the suggestions ('from your company profile'), and names the sibling where results land (campaign_ideas_list). It does not explicitly distinguish itself from campaign_ideas_get/list/launch in a 'this vs that' way, but the generation-vs-retrieval boundary is inferable.

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

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

'With segment it adds ideas for that audience instead' gives a clear conditional for the optional parameter, and naming campaign_ideas_list tells the agent where to read results. However, there is no explicit when-to-use statement (e.g. 'call this before launching anything') and no mention of prerequisites or the launch workflow that the 'not launched yet' clause hints at.

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 a non-destructive write operation, and the description adds useful behavior beyond that: the operation is free, and specific classes of contacts are silently skipped (already present, no usable email, not among your contacts). It does not cover idempotency or partial-success reporting, but the skip semantics are valuable.

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 purpose, then cost and skip behavior. No filler or redundancy; every clause adds actionable 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?

Given an output schema and fully described input schema, the description supplies the key behavioral nuance (skipped contacts). It could mention the per-call contact limit or whether failures are partial, but that is largely covered by the structured fields.

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

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

Schema description coverage is 100%, so the schema already documents both campaignId and contactIds, including their source tools and ID formats. The description adds no parameter-level meaning beyond what the schema provides, which is the expected baseline.

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

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

States a specific verb and resource: adding contacts to a campaign. It is clearly distinguishable from campaign creation/update siblings by the resource being added, though it does not name any alternative tool 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?

Implies this is for populating an existing campaign with contacts, and the 'Free' note plus skip rules give some context. However, it does not explicitly say when to use this versus campaigns_create or other sibling tools, nor does it state prerequisites in the description.

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

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

Annotations already establish that this is a non-read-only, non-destructive, closed-world operation. The description adds important behavioral context beyond annotations: the campaign starts paused, creating it is free, and it will not send until recipients are added and status is changed.

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

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

Three short sentences, front-loaded with the core action and state. The follow-up workflow is useful and no sentence 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?

An output schema exists, so return values need not be explained. The description covers the essential state change and next-step workflow; remaining complexity in steps, variations, and limits is handled by the schema.

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

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

Schema description coverage is 75%, so the schema carries most parameter meaning. The description adds no parameter-level guidance for name, steps, poolId, or dailySendingLimit, 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 verb and resource: create an email campaign. It also discloses the initial paused state, which distinguishes this from activation or update siblings. An agent can identify the tool immediately.

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

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

It gives clear post-creation routing: add recipients with campaigns_add_recipients, then activate with campaigns_set_status. It does not explicitly exclude alternatives such as campaigns_update or campaign_ideas_launch, but the create-vs-activate workflow 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/destructiveHint=false annotations already declare this is a safe, closed-world read, so the description adds no behavioral context. Its enumeration of returned fields is largely redundant because an output schema exists, and it says nothing about not-found behavior or permissions.

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 wastes no words, but it is a bare fragment rather than a front-loaded description with a guiding clause. Brevity here comes at the cost of specification rather than from efficiency.

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?

Annotations cover safety, the single parameter is fully documented, and an output schema handles return values, so little is strictly missing. The remaining gap is that nothing tells the agent to prefer this over campaigns_list for a single record lookup.

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 documents campaignId and its 24-hex pattern. The description adds no further meaning (no format example, no validity rules), 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?

Tautological: description restates name/title.

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

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

There is no statement of when to use this versus campaigns_list, campaigns_update, or campaigns_set_status, and no preconditions are mentioned. The only routing hint, campaignId coming from campaigns_create, lives in the schema rather than the description.

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

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

Annotations already declare the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description needn't re-state that. What it does add is the sort order ('newest first') and that status and counts accompany each row, which is genuine behavioral context not implied by the annotations. It stops short of saying anything about pagination, result limits, or whether archived campaigns are excluded by default.

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 clause-dense sentence with no filler, front-loading the verb and resource and packing scope, ordering, and payload into the remainder. Nothing needs trimming.

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

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

For a one-parameter read-only list tool with a fully documented schema and an output schema that defines the returned shape, the description covers what matters: what is listed, in what order, and roughly what comes back. The only omission is an explicit note that archived campaigns are hidden unless requested.

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

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

Schema description coverage is 100% and the single includeArchived parameter carries its own description with a default and enum, so the schema does the heavy lifting. The description adds no extra meaning beyond it — the word 'your' hints at account scoping but says nothing about archived inclusion.

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?

Tautological: description restates name/title.

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

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

There is no when-to-use guidance, no mention of when to prefer campaigns_get, and no explanation of when archived campaigns matter. The one real selection decision an agent faces here — whether to set includeArchived — is left entirely to the schema.

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, non-destructive, non-open-world, which does not reveal that pausing an archived campaign silently unarchives it — a genuine side effect the description surfaces. The prerequisite for "active" is also an operational constraint not present in structured data. It does not say whether setting status to the value it already holds is a no-op or what errors occur when the precondition fails.

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 primary action first and the constraint/side-effect disclosures stacked behind it. Every clause carries operational information.

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

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

Only two required parameters, one of them a plain 24-char ID, and an output schema exists, so return-value explanation is unnecessary. The description covers the transition semantics and the one surprising side effect, which is enough for an agent 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 coverage is 50% (campaignId is documented, the status enum values are bare), and the description compensates by explaining what the "active" and "paused" values actually require and do. It adds real meaning beyond the enum list rather than restating it.

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

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

The description names a specific verb (turn on/pause/archive) and resource (campaign) and enumerates the three target states, so an agent knows exactly what the tool mutates. It stops short of naming the adjacent sibling campaigns_update to say which tool handles other field changes, so sibling differentiation is only implicit from the name.

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

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

"active needs a sender pool with an active inbox" states a concrete precondition an agent must check before invoking, and the archived-campaign behavior tells the agent what state transition is legal. There is no explicit exclusion like "use campaigns_update to rename a campaign", so alternatives are not covered.

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

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

The annotations already establish this as a non-read-only update. The description adds important behavior beyond the annotations: only sent fields change, and steps are replaced wholesale, so preserving an existing step requires sending its id. That is meaningful mutation behavior, though it does not cover permissions or failure behavior.

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

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

Three short sentences, front-loaded with the changed fields and followed by the two most important invocation caveats. There is no visible 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?

The tool has a full output schema and annotations, so the description does not need to explain return values or safety. It covers the main mutation gotchas: partial field updates and step replacement. It is slightly thin on when to choose this update tool over sibling campaign operations.

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 60% schema coverage, the description compensates for the missing top-level steps guidance by explaining that steps replaces every step and that an existing step must include its id to keep personalization and past versions. Other parameters are mostly covered by the schema, and the description does not add much beyond them.

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

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

The description states a specific verb and resource: changing a campaign’s name, steps, sender pool, or daily limit. It is clear what the tool modifies, but it does not explicitly contrast itself with sibling tools such as campaigns_set_status or campaigns_add_recipients.

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 says what can be changed but gives no explicit guidance on when to use this tool versus alternatives. It also omits prerequisites or exclusions, leaving the agent to infer usage from the name and schema.

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 write. The description adds behavior annotations do not carry: it is free (useful given the credits_get sibling) and it is idempotent-by-matching ('matched and kept, never duplicated'). It does not describe partial-failure or per-item error behavior for batch submissions.

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, action and scope first, then the two behavioral facts that actually matter (cost, dedup). No filler whatsoever.

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

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

Output schema and annotations carry the return-shape and safety burden, and the description covers the two facts structured fields cannot express. Only the batch semantics (up to 1000 items, partial failures) are left 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 description coverage is 100% and the array item field set, min/max items, and the organizationId provenance note are all documented in the schema. The description adds nothing about parameter format, so baseline 3 applies.

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

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

States a specific verb (Save) and resource (contacts or organizations), and the phrase 'your own' signals it differs from the lookup/search siblings. It is clear, but it never names an alternative tool to contrast against, so differentiation is inferred rather than stated.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no named alternative among siblings such as organizations_search or contacts_list. The word 'own' faintly implies this is for user-supplied contacts rather than enriched data, but the agent must infer that.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered by structured data. The description adds one genuinely useful behavioral fact beyond that: results come back in a stable order, which tells the agent pagination is safe from skips or duplicates. It says nothing about timeouts, rate limits, or cursoring edge cases, so a 3 is appropriate.

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 clause with no wasted words, and the ordering/paging contract is front-loaded. It reads as a compressed fragment that largely restates the title, so it is efficient but slightly thin rather than exemplary.

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

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

An output schema exists, so return values need not be described, and the parameters are fully covered by the schema. For a simple two-optional-parameter list tool with full annotation coverage, the description plus structured data gives an agent enough to invoke it correctly; only the absence of sibling-routing guidance keeps it from a 5.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, establishing baseline 3. The description's mention of nextBefore ties the cursor concept to the "before" parameter and clarifies its role in paging, which is mild added value but repeats rather than extends 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?

Tautological: description restates name/title.

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

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

"Page with nextBefore" implies the iteration workflow and gives the cursor name, which is implicit usage guidance. There is no statement of when to prefer this over persons_search or contacts_create, nor any exclusion or precondition, so the guidance remains inferred 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=true and destructiveHint=false, so the safety profile is covered. The description adds no extra behavioral context such as snapshot semantics, units, or response specifics, but it does not contradict the annotations.

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

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

Three words with no filler, but the phrase is under-specified for a definition: it is a tautological noun phrase rather than an instructive sentence. Conciseness is fine, but the structure lacks a verb or usage statement.

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-only balance lookup with an output schema and safety annotations, the description provides enough to understand what will be returned. It is not a complex workflow, so the missing verb and usage note are smaller 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 input schema has zero parameters, so there are no parameter semantics to document. The baseline of 4 applies; no compensation is needed from the description.

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?

Tautological: description restates name/title.

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

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

No sentence or phrase explains when to call this tool or when to prefer an alternative. The only implied context is from the title/name, and the sibling tools are unrelated categories, so the description gives 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 that this is a non-read-only, non-destructive, closed-world operation. The description adds materially beyond that: a 25-credit charge, a 2-5 minute reporting window, and a 60-minute test expiry. Costs and timing are exactly the behavioral context annotations cannot convey.

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

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

Purpose is front-loaded and every sentence carries information (procedure, polling cadence, timing, cost). The middle sentence is long and run-on, packing three separate instructions together, so structure is efficient but not maximally scannable.

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

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

An output schema exists, so return values need not be spelled out, and the description still covers the full usage loop, expected latency, expiry, and credit cost. Nothing an agent needs to invoke this correctly is missing.

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

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

With zero declared parameters, the baseline is 4. The description goes further by naming the operative inputs (seedEmails, testId) and their intended usage, though these names do not appear in the empty schema, which creates a mild mismatch rather than a clarifying one.

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 an inbox placement test for a mailbox you send from') and immediately contrasts with the sibling 'deliverability_get_test', which it positions as the polling counterpart. An agent can distinguish the two without opening either schema.

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

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

Explicitly prescribes the workflow: send one email from the mailbox under test to every address in seedEmails with testId in the body, then poll deliverability_get_test about once per minute. It names the alternative tool and the exact trigger for using it, leaving nothing to inference.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds real behavioral context: the async waiting state, the full set of placement values including the sentinel values missing and unreadable, and how score is derived (inbox share 0–10, unreadable seeds excluded). It does not discuss error conditions or result expiry, so not 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?

It is front-loaded with the purpose and then packs field semantics into dense semicolon-linked clauses; every clause carries information. The run-on structure slightly hurts scannability 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?

For a read-only result-fetching tool with a rich output schema, the description covers what the agent needs: the polling cadence, the meaning of every placement value, and the scoring rule. Return shape is left to the output schema as expected.

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 testId parameter already documents its pattern and its origin from deliverability_create_test. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

The description clearly states the resource returned: the placement result of a test email across each seed mailbox, which pairs naturally with the sibling deliverability_create_test. The retrieval verb is implicit rather than stated, but an agent can still distinguish this from the create tool without opening the schema.

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

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

It gives an explicit operating instruction: poll roughly once per minute while status is waiting, which tells the agent both the condition to call and the cadence. It does not name an alternative tool or state when not to call, so it falls short of a full 5.

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

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

Annotations only declare readOnly/openWorld/destructive flags, so the credit-charging rule (0.5 credits, billed only on a successful match) is genuinely additive context an agent needs to avoid surprise spend. It does not, however, discuss rate limits, lookup latency, or what happens on a miss beyond the billing 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?

Three short sentences, zero filler: purpose first, return payload second, cost caveat last. Every sentence carries information the agent would otherwise lack.

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 tool with an output schema, the description needn't restate return fields, and the cost model is disclosed. The only shortfall is the absence of routing guidance against the other organizations_* siblings.

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

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

Only one parameter and schema description coverage is 100% (the schema already gives the "stripe.com" example and minLength), so the baseline of 3 applies. The description adds no syntax or normalization guidance beyond what the schema 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?

States a specific verb (enrich) applied to a specific resource (a company, keyed by domain) and even names the payload returned (firmographics, socials, website data). This clearly separates it from the sibling organizations_search, which retrieves rather than enriches.

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

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

The usage is implied — you call it when you already hold a company domain and want enrichment — but there is no explicit when-to-use versus the sibling organizations_search or organizations_find_decision_maker, and no exclusions or prerequisites 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 only say readOnlyHint=false, openWorldHint=true, destructiveHint=false — enough to signal external lookup but nothing about cost or timing. The description supplies both: a conditional 2-credit charge that fires only on success, and a multi-minute latency window. These are exactly the behaviors an agent needs before committing to a call, and nothing contradicts the annotations (a credit-consuming finder is consistent with readOnlyHint=false).

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

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

Three short sentences, each doing distinct work: what it returns, what it costs, how long it takes. The payoff statement is front-loaded and there is no filler.

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

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

With an output schema present, return-shape explanation is unnecessary, and one fully documented parameter needs little prose. The description covers the two non-obvious facts an agent must weigh — cost and latency — but says nothing about the no-result case (e.g., whether credits are untouched and what the response looks like when no decision maker exists).

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

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

There is a single parameter at 100% schema description coverage ('Company ID returned by organization search or enrichment'), so the schema already carries the meaning. The description adds no format, sourcing, or validation detail for organizationId, which is the correct baseline 3 when the schema does the heavy lifting.

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

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

States a specific verb and resource plus a meaningful qualifier: finding the decision maker of an organization, with the email verified. That is far more specific than a generic 'look up organization', though it never names how it differs from near neighbors like organizations_enrich or persons_find_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?

The scenario where this applies (you have an organizationId and want a decision-maker contact) is implied rather than stated, and no alternative tool is named as the wrong or right choice. The cost and latency hints ('charges 2 credits', 'a few minutes') do help an agent decide whether to invoke it, which lifts this above pure silence.

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 (unusual for a search tool) and the description supplies the missing context: the call consumes credits proportional to organizations returned. It also discloses the free count-only mode, which is real behavioral information not derivable from annotations or schema. It stops short of describing result ordering, pagination limits, or truncation behavior.

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

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

Three short sentences with zero filler; the capability statement comes first and the cost/count caveat follows immediately. Nothing is padded or 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?

An output schema exists and the schemas are fully documented, so the description needn't explain return values. For an 18-parameter search tool it is still thin: it never says how the filters combine (e.g. domains with query), nor whether pagination beyond offset 10000 is impossible. Adequate but with clear gaps.

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

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

Schema description coverage is 100% and every parameter, including the limit=0 trick, is documented in the schema itself. The description adds no syntax or format detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb (search/look up) and resource (organizations), and distinguishes two modes: text search versus domain lookup. It does not, however, name or contrast itself against obvious siblings such as organizations_enrich or organizations_find_decision_maker, so an agent must infer the boundary.

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

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

The cost model (0.5 credits per returned organization) and the 'limit 0 returns only totalCount, free' tip imply a cost-aware usage pattern, which is genuinely useful guidance. However, there is no explicit statement of when to use this tool instead of organizations_enrich, organizations_find_decision_maker, or businesses_search.

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 set readOnlyHint=false, destructiveHint=false, openWorldHint=false but say nothing about billing. The description adds a concrete and important behavioral fact: "Charges 1 credit only when an email is found." That conditional cost model is exactly the kind of detail annotations cannot convey. Auth requirements and rate limits are still unstated.

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

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

Two sentences, fully front-loaded: capability first, cost model second. No filler, no restated schema detail.

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

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

An output schema exists, so return values need not be explained, and the billing note covers the main hidden behavior. What remains thin is any guidance on which input combination to prefer and what happens on a miss, which matters for a tool whose cost is conditional.

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 each parameter (name, domain, linkedin) is already documented with format examples. The description only restates the two combination modes, adding no syntax or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Find a person's work email") and names the two accepted input modes, which is more than a title restatement. It does not, however, distinguish itself from near-siblings like persons_lookup or persons_search, so an agent must still infer which lookup tool to pick.

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

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

The description gives the two valid input paths (LinkedIn URL, or name plus domain), which implies usage. It never states when to prefer this over persons_lookup, persons_find_phone, or organizations_find_decision_maker, and gives no exclusions or prerequisites.

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

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

Discloses the billing rule ('charges 2 credits only when a phone number is found'), which is genuine behavioral context the annotations do not carry — readOnlyHint=false alone would not tell an agent about cost or conditional charging. It does not mention rate limits or auth requirements, but the credit policy is the material trait here.

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

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

Three short sentences, front-loaded with the action and inputs, then the scope limit, then the cost. Every sentence carries information an agent needs; nothing is padded.

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

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

With an output schema present, return values need no explanation, and the description covers scope, inputs, and cost. The only minor omission is what a successful result implies for follow-up (e.g. coverage/likelihood limits), but nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so all four parameters are already documented, including the constraint that name requires a domain. The description restates the accepted input combinations but adds no format or precedence detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Find a person's phone number') and enumerates the three accepted lookup keys, which cleanly separates it from siblings like persons_find_email or persons_lookup. The scope qualifier ('professional contacts only') further pins down what the tool returns.

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

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

Gives an explicit when-not boundary: professional/role-based contacts, not private individuals. It does not name the sibling alternative (persons_find_email) for when a phone is not the target, so the routing guidance is clear but not fully comparative.

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

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

Adds genuinely useful behavior beyond the annotations: the credit model ('charges 1 credit only when the person is found with an email or phone') and the side effect that saveToContacts persists the person to contacts, which explains why readOnlyHint is false despite the read-like name. It stays silent on rate limits and result freshness, so not 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?

Four tight sentences with the purpose front-loaded, followed by return contents, scope constraint, and billing behavior. No sentence is redundant with the name/title and nothing is padded.

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

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

With an output schema present, the brief return summary is sufficient, and the billing plus scope caveats cover the main decision-relevant facts. It could still specify which standalone identifiers (email alone, LinkedIn alone) are valid without a domain, but the core is 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 description coverage is 100%, so the schema already documents all five parameters including the 'needs domain' constraint on name. The description only echoes the identifier list and adds a note on saveToContacts, so baseline 3 is appropriate.

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

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

States a specific verb (look up), cardinality (one person), and the exact identifiers accepted (LinkedIn URL, email, name + company domain). This distinguishes it from plural siblings like persons_search and the narrower persons_find_email/persons_find_phone without the agent needing to open 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?

Provides a clear scope boundary — 'professional contacts only: people in their role at a company, not private individuals' — which tells the agent when this tool will fail. It does not, however, route the agent among alternatives such as persons_search for broader matching, leaving sibling selection to inference.

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

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

Annotations already declare a non-read-only, non-open-world, non-destructive profile, so the bar is lower. The description nonetheless adds substantive context beyond them: 1 credit per returned person, refunds for already-stored contacts, a free count via limit 0, and the saveToContacts side effect on the contacts store.

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 dense sentences, front-loaded with the core verb+resource+scope before cost and pagination details. Every sentence carries information, though the limit/offset and saveToContacts notes partly duplicate the schema and could be trimmed.

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

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

With an output schema present (so return values need not be explained) and 100% schema coverage, the description still covers purpose, scope, cost, pagination, and the saveToContacts side effect. It omits auth/rate-limit context, but for a search tool of this complexity it is largely 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 description coverage is 100%, so the schema already documents all 26 parameters; this is the baseline 3. The description echoes a few of them (limit 0 free count, nextOffset pagination, saveToContacts storage) without adding syntax or format detail the schema lacks.

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 ('Search persons with their emails and phones') and adds a scope restriction ('professional contacts only ... not private individuals'). It distinguishes the domain from a likely private-individual lookup sibling, but does not name an alternative tool, so it stops short of full sibling differentiation.

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

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

It gives a clear usage condition and an implicit exclusion ('people in their role at a company, not private individuals'), plus cost-aware guidance ('limit 0 returns only totalCount, free'). It does not explicitly route the agent to an alternative sibling when the exclusion applies, so the guidance is clear but not complete.

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

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

The description adds substantial behavioral detail beyond annotations: it reads from the service's own crawl, answers in under a second, never visits the site during the call, and charges 0.5 credits only when an email or phone is found. These details clarify latency, data source, side effects, and billing conditions.

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

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

The description is front-loaded with the core purpose and then adds only high-value operational details: crawl source, speed, shared-site limitation, and credit charge. Every sentence contributes useful information without redundancy.

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

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

For a single-parameter read operation with an output schema, the description covers the important call-context details an agent needs: what is returned, where the data comes from, expected speed, limitations, and cost. Nothing essential is missing.

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

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

There is only one parameter, and schema description coverage is 100%, with the schema giving the URL/domain format and an example. The description does not add further parameter semantics beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: find emails, phones, and social profiles published on a company website. It is clearly distinguishable from person-level tools like persons_find_email and persons_find_phone by emphasizing contacts published on a company website.

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 a clear usage context and an explicit exclusion: websites shared by many businesses, such as site builders or booking platforms, have no contacts. It does not explicitly name sibling alternatives for person-level lookups, so it falls short of full when-to-use-vs-alternatives guidance.

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

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

Goes well beyond the annotations by disclosing the cost model (0.25 credits, charged even on zero-pixel hits, free when the homepage never answers), the latency ceiling (up to 20 seconds), and the caching rule (answers from the last check via checkedAt, otherwise checks live). These are the exact traits an agent needs before committing credits and waiting on a slow call.

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

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

Front-loaded with the purpose, then scope, then cost/latency caveats in a logical order. The enumeration of fifteen pixel vendors is long but arguably earns its place by defining detection coverage; it could have been condensed without losing 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?

An output schema exists, so return values need no explanation. The description covers the remaining agent-critical unknowns for an open-world, credit-charging check: detection scope, platform-container exclusions, caching, latency, and pricing.

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

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

Only one parameter, and the schema already documents it at 100% coverage with an example ("castledental.com"). The description adds no format guidance beyond that, which is acceptable given the schema does the work — baseline 3.

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

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

Names a specific verb ("Find") and a precise resource ("the ad and analytics pixels a website runs"), then enumerates exactly which pixel vendors are detected. This cleanly separates it from the sibling websites_find_contacts, which looks for people rather than tracking tags.

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 operating context: it inspects the homepage plus every GTM container, and deliberately omits containers loaded by 50+ websites because those belong to a platform or agency. That is an implicit exclusion telling the agent what results will and won't include. It stops short of naming an alternative tool or stating explicit when-not-to-call conditions.

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