linkedin-buying-signals

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

Annotations only indicate non-read-only and non-destructive, but the description adds valuable behavioral details: it enriches profiles, skips already-saved entries (idempotency), and counts against the import quota. This is useful operational context that helps the agent anticipate side effects beyond what annotations or schema provide.

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 sentences that front-load the core purpose and then state the two most important behavioral notes (skip duplicates, quota impact). There is no waste and no redundant restating of the tool name or title.

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

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

For a tool with two simple parameters and no output schema, the description covers key operational aspects: enrichment fields, deduplication, and quota impact. It does not mention request size limits or error handling, which is a minor gap but not critical for tool selection or basic invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description indirectly maps the linkedinUrls parameter to the action of saving profiles, but it does not add new meaning to listId or the URL format beyond what the schema already provides. The description does not compensate further for parameter semantics.

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 tool saves LinkedIn profiles as prospects and enriches them, listing specific enrichment fields like name, role, and company. It distinguishes the tool's input type (URLs) from sibling tools, though it doesn't explicitly name alternatives like import_sourced_leads. Overall it is a specific and understandable purpose.

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

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

The description implies the tool should be used when you have LinkedIn URLs to save as prospects, but it does not mention when to prefer it over sibling tools such as import_sourced_leads. There are no explicit exclusions, prerequisites, or conditions that would help an agent choose between this and similar tools. Guidance is left purely 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?

Beyond the sparse annotations (readOnlyHint false, destructiveHint false), the description discloses significant behavioral traits: it counts against the monthly analysis quota, is slow ('expect up to a few minutes'), and enforces that every retained signal must quote its source verbatim. These are exactly the kind of non-obvious side effects and constraints an agent needs to know.

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

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

Three sentences, each earning its place: the first states the core pipeline, the second clarifies an important output constraint, and the third flags cost and latency. All information is front-loaded with the main action, and there is zero padding.

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

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

The description is complete for a complex side-effecting tool: it covers the pipeline steps, quota, latency, and the source-quoting constraint. The only gap is that with no output schema, it does not explicitly state what the tool returns (e.g., a list of detected signals, updated prospect records, or both), which would fully close the loop for an agent.

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 does not add parameter-specific detail beyond what the schema already provides; it only refers to 'prospects' generically. No additional semantics for limit or prospectIds are offered, so the schema carries the weight.

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 specific verb and resource: 'Run the signal pipeline on prospects', then enumerates the three concrete steps (enrich, read LinkedIn activity, detect buying signals). This clearly distinguishes it from siblings like list_prospects or find_leads_from_signals, which have different verbs and resources.

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 when to use the tool—when you want to analyze prospects for buying signals—but does not explicitly state alternatives or exclusions. There is no 'use X for Y instead' guidance, so an agent must infer the appropriate context from the sibling list and the stated pipeline.

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 and destructiveHint=false. The description adds that the signal is a persistent account-level addition that will influence future analyses and sourcing, which is meaningful behavioral context beyond the structured 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 with no filler: the first defines the action and gives a concrete example, the second explains downstream effect. Every sentence earns its place.

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

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

For a simple creation tool with two required parameters and no output schema, the description is largely sufficient. The main missing piece is the meaning of the two optional example fields, but this does not block correct invocation.

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

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

The schema documents 'name' and 'detects' well, and the description reinforces the plain-language nature of 'detects' with an example. However, the optional 'exampleTitle' and 'exampleDetail' parameters remain undocumented in both schema and description, so the description only partially compensates for the 50% schema coverage.

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 clear verb and resource: 'Teach the account a new buying signal'. It provides a concrete example and explains that the signal will be used in future analyses and sourcing, which distinguishes it from sibling tools like list_signals and find_leads_from_signals.

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 makes the usage context clear: invoke this when teaching the account a new signal described in plain language. It does not explicitly name alternatives or state when not to use it, but the context is sufficient.

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 meaningful behavioral context beyond annotations: 'Saves the draft on the prospect' (persistent mutation), 'returns it' (output), and 'Does not send' (critical side-effect disclosure). Annotations only state readOnlyHint=false and destructiveHint=false, so this extra detail is essential for safe invocation.

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 concise sentences each add value: main action, side effect, and exclusion. Front-loaded with what the tool does first, followed by important caveats. No filler or redundancy.

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

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

For a tool without an output schema, the description's 'returns it' is vague about whether the return is the full text, a draft object, or an ID. The schema marks all parameters as optional, but the description implies a prospect is needed, and it doesn't explain how prospectId vs linkedinUrl relate. The regenerate parameter and its caching behavior are not addressed, leaving an agent uncertain about when to set 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?

With only 40% schema description coverage, the description partially compensates: 'in their language' maps to the language parameter, 'built from their detected signals' adds context to signalIndex. However, prospectId, linkedinUrl, and regenerate are not explained; the description doesn't clarify that regenerate bypasses cached drafts or what linkedinUrl is used for. This leaves meaning gaps for 3 of 5 parameters.

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 tool drafts a personalised email for a prospect, using detected signals and language. It distinguishes itself from send_email by explicitly noting it does not send, and from draft_linkedin_message by focusing on email. The verb 'write' and resource 'email for a prospect' are specific and actionable.

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 when to use this tool: when you need a draft to review or later send. The explicit 'Does not send' serves as a clear exclusion, indicating send_email should be used for sending. However, it doesn't directly name sibling alternatives or provide explicit when-not-to-use conditions beyond not sending.

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

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

Despite annotations lacking readOnlyHint and destructiveHint defaults, the description explicitly states 'Saves the draft and returns it. Does not send.' This discloses the save behavior and non-sending action, which is beyond what annotations provide. It adds behavioral clarity about persistence and side-effects.

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 with clear front-loading of the action and key constraints (language, saves, not sends). Could be slightly more structured but is efficient with no waste. The 'Does not send' is a crucial differentiator placed at the end.

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 drafting tool with no output schema, the description covers the core behavior. It doesn't explain return format or the meaning of each parameter, but given the tool's simplicity and that annotations exist, it's adequate. The regenerate parameter is left unexplained, but the description is complete for basic usage.

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 0% schema description coverage, the description must compensate. It mentions 'their language' relating to language parameter, and 'prospect' implying prospectId. It doesn't explain regenerate or linkedinUrl, but the core parameters are implied. Since description covers the main purpose, it partially compensates for the schema gap.

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

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

The description clearly states the action (write a short LinkedIn connection note), the input (prospect's detected signals), and the language requirement (in their language). It also explicitly notes it saves the draft but does not send, distinguishing it from send_linkedin_message. This is specific and unambiguous.

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

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

The description implies when to use it (when drafting a LinkedIn message for a prospect, not sending) and contrasts with send_linkedin_message. However, it doesn't explicitly state when not to use it or mention alternatives like draft_email, but the sibling list makes it clear it's the LinkedIn-specific drafting tool. Clear context with implicit exclusion.

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 note readOnlyHint=false and destructiveHint=false; the description adds the concrete side effect of spending monthly sourcing budget and clarifies that no data is saved. It also hints at a verification step ('a check can prove are on topic'). This goes beyond annotations and is consistent with them—no contradiction.

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

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

Four tight sentences front-load the main action, then add scope and side-effect details. Zero filler; every sentence earns its place. The structure leads with the core behavior and ends with the budget note.

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 tool with only two optional parameters and no output schema, the description provides all needed context: what it returns (people who wrote/commented/reacted), the filtering criteria (ICP), the non-persistent nature, and the follow-up tool. Nothing essential for an agent to call it correctly is missing.

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

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

Schema coverage is only 50% (postsPerSignal lacks a description). The tool description does not explain postsPerSignal at all, leaving its meaning to the default and name. signalType is only implicitly connected to 'signal definitions'. The description fails to compensate for the low schema coverage, so parameter semantics are inadequately communicated.

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+resource: search LinkedIn posts on signal topics, filter against ICP, and return people. It clearly distinguishes itself from siblings like import_sourced_leads by specifying that nothing is saved and candidates should be passed there. This is a precise, non-tautological purpose.

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 explicit workflow guidance ('pass the returned candidates to import_sourced_leads') and notes the budget cost. It does not name alternative tools or state when not to use it, but the use case is clear enough. Lacking explicit exclusions keeps it from a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the behavioral context that the returned ICP is the active one and that it is the basis for sourcing and scoring filters. It does not describe return format or whether the ICP can be empty, but for a read-only getter with no parameters, the description adds adequate context beyond 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?

Two sentences, no filler. The first sentence enumerates the content of the ICP, and the second explains its role in sourcing and scoring. Every word earns its place, and the most important information is front-loaded.

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

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

For a zero-parameter, read-only getter with no output schema, the description is nearly complete. It tells the agent what the tool returns and why it matters. The only minor gap is that it doesn't specify the return format (e.g., JSON structure), but with no output schema and no parameters, the description covers what an agent needs to decide to call it.

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

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

The tool has zero parameters, so the schema provides no parameter semantics to speak of. The description compensates by explaining what the returned resource contains, which is the only semantic information an agent needs. With 0 params, the baseline is 4, and the description meets that baseline by describing the output content.

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

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

The description clearly states the tool returns the active ICP and enumerates its components (target roles, industries, countries, company sizes, keywords, exclusions). It distinguishes itself from sibling tools by framing the ICP as the filter used by sourcing and scoring, which is a distinct resource. It doesn't explicitly name a sibling alternative, but the resource is specific enough that an agent can tell it apart from tools like get_pipeline_stats or list_prospects.

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 when to use this tool: when an agent needs to know what sourcing and scoring filter against. It does not explicitly state when not to use it or name alternatives, but the context signal 'This is what sourcing and scoring filter against' gives a clear use case. There is no exclusion guidance, so it stops at implied usage rather than explicit routing.

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 no contradiction. The description adds useful behavioral scope by listing what the stats include, such as enrichment state and remaining quota, but it does not describe the response shape or whether output is one summary object versus a table. For a read-only aggregate, this is adequate but not rich.

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 a single efficient sentence with the core purpose front-loaded ('How the pipeline stands') followed by a compact list of covered metrics. It is slightly run-on, but no words are 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 input parameters, no output schema, and read-only annotations, the description carries the full responsibility for explaining what the tool returns. It lists all major report dimensions, which is enough for an agent to know what to expect, though it leaves terms like 'enrichment state' and the exact response format implicit.

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

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

The tool has zero parameters, so there is no parameter documentation burden; the baseline of 4 applies. The description appropriately focuses on the metrics returned rather than 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 clearly identifies the tool as a pipeline-wide status/summary reporter by enumerating the exact metrics it covers (prospect counts, enrichment state, email availability, contacts, 7-day additions, signal types, quota). It stops short of an explicit verb like 'retrieves' and does not name sibling alternatives, but the aggregate nature is unmistakable and distinct from list/get/send siblings.

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 metric list strongly implies this tool is for high-level pipeline overview questions rather than per-record operations such as get_prospect or list_prospects. However, it never explicitly states when to use it versus a sibling, and it does not mention any exclusions or 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 establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful return-content context: it discloses that signals include verbatim quotes and LinkedIn source URLs, and that existing drafts and outreach state are included. No contradiction with 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 dense sentence front-loads the core purpose ('Everything known about one prospect') and then lists concrete fields. Every clause adds information; there is no filler or repetition.

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

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

The description gives a strong inventory of returned fields, which is valuable given no output schema. However, it does not clarify how to choose between the two optional parameters, what happens if both or neither are provided, or any fallback behavior. For a simple lookup tool this is a noticeable 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 the schema already documents prospectId and linkedinUrl. The description does not add parameter-level guidance beyond indicating that the tool returns everything known about one prospect, which is enough to meet the baseline but not exceed it.

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

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

The description states a clear resource ('one prospect') and enumerates the specific data it returns: role, company, location, language, signals, verbatim quotes, source URLs, drafts, and outreach state. This distinguishes it from siblings like list_prospects and get_pipeline_stats by focusing on full detail for a single prospect.

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: this is for retrieving everything known about one prospect, while list_prospects is the obvious alternative for listing. However, the description never explicitly says when to use this tool versus alternatives, nor does it state that prospectId or linkedinUrl is the expected entry point.

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 indicate non-read-only and non-destructive behavior. The description adds meaningful behavioral context: candidates arrive enriched, the signal is attached, the verbatim quote is included, and the operation counts against the import quota. This goes beyond the annotations, though duplicate handling and idempotency are not addressed.

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

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

Three sentences with no filler. The core action is front-loaded, followed by relevant input characteristics and a quota warning. Every sentence earns its place.

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

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

For a small tool, the core call is well specified, but the description omits what listId does, how duplicates are handled, and what the tool returns after a successful import. Since there is no output schema, some of this information would be useful for an agent to invoke it confidently.

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

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

The schema already documents tokens and signalType (67% coverage). The description reinforces that signalType comes from find_leads_from_signals, but adds no meaning for listId, the only undocumented parameter. It provides moderate but not complete parameter clarification.

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 ('Save') and a clear resource ('candidates returned by find_leads_from_signals'), which immediately differentiates it from find_leads_from_signals and add_leads_from_urls. It states exactly what the tool does without ambiguity.

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

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

The description strongly implies usage context: this is the tool to persist the candidates that find_leads_from_signals returns. It does not explicitly name alternatives or say when not to use it, but the source-tool reference provides clear selection context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavior beyond that: it documents ordering by signal count and recency. However, it does not disclose response shape, pagination behavior, or how filters interact, which would add further transparency.

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 efficient sentences with the core purpose front-loaded: 'Search the saved prospects in the account.' The filter list is compact, and the ordering statement earns its place. No filler or redundant restatement of the tool 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?

For a tool with 12 optional parameters and no output schema, the description gives a solid high-level overview but leaves notable gaps: it does not state whether filters are ANDed, explain return fields, mention pagination beyond the schema, or clarify value formats (e.g., country codes, enrichment status values). It is adequate for tool selection but not fully complete for invocation without schema inspection.

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

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

Schema description coverage is only 50%, so the description carries some burden for parameter meaning. It does map several parameters to plain language ('hasEmail' becomes 'whether an email address is known', 'enrichmentStatus' becomes 'enrichment state', 'notContacted' becomes 'whether they have been contacted'). However, it adds little beyond restating the parameter concepts and omits offsets, limit, and search-text semantics.

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 ('Search') and a clear resource ('saved prospects in the account'), which distinguishes it from siblings like find_leads_from_signals that operate on signal-derived leads rather than saved prospects. It also enumerates the available filter dimensions, making the tool's 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?

The description makes the intended use clear: searching and filtering saved prospects. It does not explicitly name alternatives or state when not to use it, but the phrase 'saved prospects' and the filter list provide enough context to route an agent correctly relative to the sibling tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context beyond that: it explains that signals are account-scoped, include both predefined and custom definitions, and expose an enabled flag. It also indicates the returned type values are intended for downstream 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?

The description is reasonably concise and front-loaded, with the core purpose stated first and the downstream usage in a short second sentence. It is slightly wordy in the first sentence but every part contributes 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 simple read-only listing tool with one optional parameter and no output schema, the description covers purpose and output content well. However, it omits the enabledOnly parameter semantics, which is a meaningful gap because the parameter directly changes what signals are listed.

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% for the only parameter, enabledOnly. The description never explains this parameter, its default behavior, or how changing it affects results. The word 'enabled' in the description hints at the concept but does not clarify that enabledOnly controls whether disabled signals are included.

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 that this tool lists the buying signals for the account, distinguishes predefined from custom signals, and specifies the output includes the detection definition and enabled status. It is clearly differentiated from siblings like create_custom_signal, and its relationship to list_prospects and find_leads_from_signals is explicit.

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

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

The description gives clear context for when to use this tool: to obtain signal type values needed by list_prospects and find_leads_from_signals. It does not explicitly state when not to use it or name alternatives like create_custom_signal, so it falls just short of a 5.

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

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

Annotations already indicate a non-read operation and non-destructive intent. The description adds that the record 'keeps reporting and follow-ups correct,' hinting at downstream state effects, but it does not disclose details such as idempotency, overwriting, or which prospect record gets updated. No contradiction with 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 14-word sentence that front-loads the action and appends the purpose. No filler or repetition 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 tool with no output schema and no parameter descriptions, the description leaves a critical gap around how to identify the prospect. The basic use case is clear, but the absence of required parameters and alternative identifier semantics makes it incomplete for correct invocation.

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

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

Schema description coverage is 0%, and the description never mentions prospectId or linkedinUrl. With zero required parameters, an agent cannot tell whether one identifier is sufficient, whether both are needed, or how linkedinUrl relates to prospectId. The parameter names are readable, but the description does not compensate for the missing schema docs.

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 resource: 'Record that a prospect was emailed outside getcleed.' The phrase 'outside getcleed' immediately distinguishes it from sibling tools that actually send email, such as send_email, and clarifies its bookkeeping role.

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

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

The description gives clear context by specifying the tool is for emails sent outside getcleed, implying it is not for emails sent through getcleed. It does not explicitly name alternative tools or say 'use send_email instead,' so it stops just short of full routing guidance.

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

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

Annotations already flag destructiveHint=true, and the description adds concrete context by stating 'reaches a real person immediately and cannot be undone' and requiring a connected mailbox. This goes beyond the annotation's generic destructive flag to describe the irreversibility and delivery guarantee.

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 with no filler. The main purpose is front-loaded, and the key behavioral warning and parameter usage are concisely stated.

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 description covers the action, prereqs, and parameter behavior for half the parameters, but it omits the purpose of prospectId and linkedinUrl, and does not mention expected outcomes or errors. For a simple mutating tool, this is a notable 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 descriptions cover body and subject (50% coverage), and the description clarifies that omitting them uses the saved draft. However, prospectId and linkedinUrl have no descriptions in the schema or the tool description, leaving their role ambiguous for identifying the recipient.

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 it sends an email to a prospect, identifying the channel (email vs LinkedIn) and the action (send). It differentiates from sibling tools like draft_email and send_linkedin_message by specifying the connected mailbox and real-time delivery.

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 provides a prerequisite (connected mailbox) and explains when to omit parameters to send a draft, but it does not explicitly state when to use this tool versus alternatives like draft_email or send_linkedin_message. The guidance is mostly implicit.

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

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

Annotations already mark destructiveHint=true, and the description adds critical context: 'reaches a real person immediately and cannot be undone' and the integration requirement. This goes beyond the annotation and informs the agent of irreversible side effects and setup needs.

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

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

Three sentences, no fluff, action front-loaded, important caveats (irreversibility, integration requirement) included. Every sentence earns its place.

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

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

No output schema exists, so the description should explain what happens on success/failure, but it does not. Two of three parameters are undocumented, and the description does not clarify how to specify the prospect (via prospectId or linkedinUrl). The tool is incomplete for correct invocation.

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

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

Schema description coverage is only 33%, with only 'message' explained. The description elaborates on the 'message' parameter ('Pass the note you want sent, or omit it to use the saved draft') but provides zero clarification for prospectId and linkedinUrl, which are left entirely to the schema's bare names. The description fails to compensate for the low coverage.

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 ('send'), resource ('LinkedIn connection request'), and target ('prospect'), and clearly distinguishes it from siblings like draft_linkedin_message and send_email. It's unambiguous about what the tool 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?

The description provides the prerequisite (LinkedIn connected in getcleed under Integrations) and implies it is for actual sending rather than drafting, but does not explicitly route the agent to alternatives like draft_linkedin_message for drafting. The 'cannot be undone' warning is helpful but not a usage guideline. No explicit when-to-use vs. when-not-to-use is given.

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