SignalRaven

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

Beyond the minimal annotations, the description discloses a critical behavioral side effect: 'CHANGES WHERE YOUR DATA IS SENT: every future signal matching the routing rule will be delivered there.' It also adds a constraint ('Subject to your plan's destination limit') and a validation requirement ('config must match the shape for the chosen type'). This is exactly the kind of behavioral context the annotations do not 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 compact and every sentence earns its place: the core creation action, the destination-type examples, the critical side-effect in an attention-grabbing caps phrase, the config-type coupling, and the plan-limit caveat. No filler or redundant restatement of the name/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?

The description covers the main points an agent needs before calling: what the tool does, the important routing side effect, the config/destinationType dependency, and the plan limitation. An output schema exists, so return-value details are not required. It slightly under-specifies comparison with update_destination and does not mention all enum values, but those are minor given the schema and sibling names.

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?

Even though the schema has 100% description coverage, the tool description enriches the parameters by linking config to the chosen destinationType ('config must match the shape for the chosen type') and clarifying the routing parameter's behavioral effect ('every future signal matching the routing rule will be delivered there'). This goes beyond the schema's generic descriptions.

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

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

The description states a specific verb and resource: 'Create a new place for signals to be delivered' and then elaborates with concrete destination types (Slack, webhook, Google Sheet, n8n, Clay, Notion). It distinguishes from update_destination by emphasizing 'new' and from read tools by describing creation. The purpose is 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 implies the tool is for creating a new destination and explains the effect on future signal routing, giving clear context. However, it never explicitly says when to use this instead of sibling tools like update_destination or list_destinations, and there are no stated exclusions or alternative tool mentions. Usage is inferred, not spelled out.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the content detail (firmographics, ICP disposition, buying committee) which is useful but not critical. No extra behavioral context (e.g., pagination, caching) is disclosed, but with annotations covering safety, this is adequate.

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

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

One sentence, front-loaded with the action and scope, followed by a concise list of report contents. No wasted words, and the critical info (what the report includes) is placed early.

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?

Complexity is low (one parameter, no nested objects), and an output schema exists, so return values are documented elsewhere. The description covers what the report contains, and annotations cover safety. Nothing an agent needs 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 100%, with the single 'id' parameter described as 'The Account Intelligence report id.' The description adds nothing beyond what the schema already provides. Baseline 3 applies because the schema fully documents the parameter.

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

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

States a specific verb ('Fetch'), a precise resource ('one Account Intelligence report by id'), and enumerates the report's contents (firmographics, ICP disposition, buying committee). This clearly differentiates it from siblings like run_account_intelligence, which generates new reports, and get_icp, which targets ICP data alone.

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

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

The description clearly implies the use case: retrieve an existing report when you have its id. It doesn't explicitly mention alternatives or exclusions, but the presence of siblings like run_account_intelligence and list_intelligence makes the distinction implicit. Lacks an explicit 'use this when' statement, hence 4 rather than 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, covering the safety profile. The description adds that it returns the workspace's default ICP and that this profile drives signal scoring, which gives modest context beyond the schema. It does not describe response format, but the output schema exists and covers that.

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 sentence that immediately states the resource and qualifiers. It is front-loaded, contains no filler, and every word earns its place—an ideal length for a no-parameter read tool.

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 no-parameter, read-only tool with annotations and an output schema, the description is complete. It tells the agent what the resource is and its scope (workspace default), leaving nothing about invocation unclear.

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 baseline is 4 per the rubric. The description adds value by reinforcing what the resource is, but there are no parameter semantics to clarify; the schema already documents the empty input.

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 verb 'Get' and the specific resource 'your workspace's default Ideal Customer Profile', enumerating its components (target industries, titles, personas, seniority, company-size band). This distinguishes it from sibling getters like get_signal or get_account_intelligence by naming the exact subject and 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 when to use this tool—when you need the default ICP profile—but does not explicitly contrast it with alternatives or state exclusions. Given the tool takes no parameters and the context is a simple read, the implied usage is adequate, though more explicit routing to sibling intelligence tools would be an improvement.

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 this read-only and non-destructive, and the description agrees. It adds useful context about the returned contents, but does not disclose additional behavioral traits such as freshness, permissions, or error 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?

A single front-loaded sentence that states the operation, the scope, and the key result contents with no wasted words.

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

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

For a one-parameter read-only tool with an output schema and safety annotations, the description is largely complete. It could mention the relationship to run_person_intelligence or what happens when the snapshot id does not exist, but those are minor.

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 id parameter is already fully documented; the description's 'by id' adds no new format or constraints beyond the schema. Baseline 3 is appropriate.

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

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

The description names a specific verb ('Fetch') and resource ('one Person Intelligence snapshot by id') and enumerates the contents (profile, buyer read, flags, signals), so an agent can distinguish it from list_intelligence or get_account_intelligence 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?

The phrase 'by id' gives a clear retrieval context: use this when you need a single existing snapshot and have its identifier. It does not explicitly name alternatives or exclusion criteria, so it stops short of a 5.

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

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

Annotations already mark readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by enumerating what 'full detail' includes (person, ICP analysis, why-it-matters, suggested opener, talking points), which tells the agent the kind of information it can expect. No additional traits like rate limits or errors are mentioned, but none are critical for this simple read operation.

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

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

A single sentence that front-loads the action ('Fetch one signal by id'), states the scope ('full detail'), and then lists the detail components without waste. Every part earns its place and there is no redundant elaboration.

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

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

The tool has an output schema, so return values are documented elsewhere. The description provides enough context about what the tool does (single signal fetch, full detail) and what the one parameter means (id). Given the low complexity and the presence of output schema and annotations, nothing essential is missing 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 coverage is 100% and the parameter id is described in the schema as 'The signal id.' The description only repeats that the tool fetches by id and does not add format, example, or source information beyond what the schema already provides. According to the calibration, baseline 3 is appropriate when the schema carries the full semantic load.

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 ('Fetch') and clearly identifies the resource ('one signal by id') with the exact scope of detail ('person, ICP analysis, why-it-matters, suggested opener, talking points'). It differentiates itself from list_signals and other siblings like get_person_intelligence by emphasizing a single signal with full detail, so an agent can select it without opening schemas.

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 context is clear: this is for fetching a single signal when the id is already knownibus. It does not explicitly say 'use list_signals for multiple or filtered signals' or mention when not to use it, but the phrase 'one signal by id' clearly implies the appropriate scenario. No explicit exclusions or alternatives are provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds useful detail about the aggregate nature of the data and explicitly excludes billing figures, but it does not discuss return formatting, pagination, or any operational behavior beyond the counts themselves.

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 sentence that front-loads the core concept and then lists specifics with an em dash. Every word adds information, and there is no filler or repetition 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?

Given the tool has no parameters and an output schema exists, the description fully covers what an agent needs to know: what metrics are included, that it is counts-only, and that billing figures are absent. Nothing required for correct invocation is missing.

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

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

The tool has zero parameters, so there are no parameter semantics for the description to clarify. The description appropriately stays focused on what the tool returns, which is the correct role for a no-input endpoint.

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 resource (workspace usage) and enumerates the specific metrics returned, such as signals, active sources, posts monitored, and discovery runs. It is not a tautology and the scope is obvious, but it does not explicitly differentiate itself from sibling tools like list_signals or get_signal.

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

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

The phrase 'Workspace activity counts' implies this tool is for high-level usage metrics rather than detailed data, and 'Counts only, no billing figures' sets an expectation boundary. However, it does not explicitly state when to choose this tool over alternatives or mention exclusions relative to 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, so the safety profile is covered. The description adds useful context about returned content (relevance scores and lifecycle status), but it does not disclose other behavioral details such as ordering, pagination semantics beyond schema, or any rate limits.

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, front-loaded sentence that names the action, resource, and key output attributes without filler. Every phrase adds value and the em-dash construction keeps the core meaning immediate.

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

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

This is a simple read-only list operation with full parameter schema coverage, an output schema, and safety annotations. The description sufficiently defines 'watchlist' and indicates the returned data, so an agent has what it needs to invoke the tool correctly.

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

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

Schema description coverage is 100%, with limit and offset already described in the schema. The tool description adds no parameter-level meaning beyond saying it lists posts, so it neither improves nor harms parameter understanding. 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 starts with a specific verb ('List') and a clear resource ('LinkedIn posts on your watchlist'). It further scopes the resource with 'qualified posts SignalRaven is tracking for engagement', which distinguishes it from generic signal-listing siblings like list_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 implies the tool is for retrieving watchlist posts, but it does not explicitly state when to use this over alternatives like list_signals or get_signal, nor does it mention any exclusions. The 'watchlist' qualifier provides context, but without explicit routing guidance the agent must infer the intended use case.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, and the description goes further by revealing that health and recent failure state are included. Most importantly, it discloses that connection settings such as URLs and tokens are never returned, a privacy-relevant behavioral trait not present in structured data. This is valuable transparency 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?

The description is two sentences with no filler. The first sentence conveys the core function and return content, and the second adds a critical privacy caveat. Every phrase 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 no-parameter listing tool with an output schema, annotations covering safety, and clear read-only semantics, the description is complete. It tells the agent what will be returned, what will not be returned, and what health information is available. No important calling context is missing.

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

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

The tool has zero parameters and an empty input schema, so there is nothing for the description to add about parameter semantics. Per the zero-parameter baseline, this is a 4; the description correctly focuses on behavior rather than inventing parameter guidance.

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

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

The description names a specific verb ('List'), the resource ('destinations'), and the scope ('where your signals are delivered'), making the tool's function immediately clear. It also distinguishes itself from sibling create/update destination tools by emphasizing read behavior and from list_sources/list_signals by focusing on destinations. The added detail about health and failure state sharpens the purpose beyond just a generic list.

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

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

The description gives clear context for when this tool is useful: when an agent needs to see delivery destinations and their health/failure status. It does not explicitly state when not to use it or name alternatives, but the read-only framing and the privacy caveat implicitly guide an agent away from expecting destination creation or credential access. This is solid contextual guidance without explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read-only nature is covered. The description adds useful behavioral context beyond that: results are newest-first, scoped to the workspace, and include specific fields per report family. This is meaningful operational detail without contradicting 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 core action is front-loaded, the resource scope follows, and the ordering behavior is included efficiently. Every phrase 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?

Given the read-only annotations, fully documented parameters, and presence of an output schema, the description covers everything an agent needs: what is listed, the scope, the ordering, and the distinguishing content of each report family. Nothing critical 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 the baseline of 3 applies. The description adds context about the returned fields per report type, which indirectly helps with the 'type' parameter, but it does not add new meaning to q, limit, or offset beyond what the schema already documents.

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 ('List') and a precise resource ('Account and Person Intelligence reports run in your workspace'), then clarifies the content of each report family (ICP disposition, buying-committee size, title, signal count). This clearly distinguishes the tool from sibling get_ and run_ tools without needing to inspect their schemas.

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 listing use-case clear and scopes it to reports already run in the workspace. It does not explicitly name alternatives such as get_account_intelligence or run_account_intelligence, but the framing is contextual enough that an agent can infer listing vs. fetching vs. generating. No exclusions or when-not-to-use guidance is provided, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint and destructiveHint, covering the safety profile. The description adds useful behavioral context: workspace scoping, newest-first ordering, and the anatomy of each signal (person, why it matters, suggested opener). 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, well-structured sentence that front-loads the action and resource, then adds the most decision-relevant details. Every clause earns its place; 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?

Given the read-only annotations, complete parameter documentation, and presence of an output schema, the description is nearly sufficient. It explains what makes these signals distinct and the ordering, though it could briefly note that optional filters are available.

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 input schema fully documents all four optional parameters including defaults, ranges, and filter semantics. The description adds no parameter-level detail, but the baseline of 3 applies because the schema carries the burden.

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 ('List') and a clear resource ('buying-intent signals SignalRaven detected for your workspace'). It also describes the output contents and ordering, distinguishing it from the singular get_signal and from list_intelligence.

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

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

The description implies usage: call this to get the workspace's detected signal feed, newest first. However, it does not explicitly state when to use it versus alternatives like get_signal or list_intelligence, nor does it mention exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful content context about what is listed, but it does not disclose behaviors like pagination, ordering, or result limits, which is acceptable but not exceptional.

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, well-structured sentence with no filler. The resource, scope, and return content are all front-loaded and scannable, making it easy for an agent to parse quickly.

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

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

For a simple, read-only list tool with no required parameters, full schema coverage, and an output schema available, the description plus structured metadata is sufficient. An agent has everything needed to select and invoke the tool correctly.

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

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

Schema description coverage is 100%: the only parameter, period, is fully documented with enum values and a default. The description adds no additional parameter nuance, so the baseline of 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 uses a specific verb-resource pair ('List your monitored LinkedIn sources'), enumerates source types (keyword searches, tracked profiles/companies), and names the included metrics (signal counts, qualified posts, strength). This clearly distinguishes it from sibling list tools like list_signals and list_destinations.

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 use case clear: call this tool when the agent needs monitored LinkedIn sources and their activity metrics. It does not explicitly name exclusions or alternative tools, but the context is specific enough that an agent can infer when it applies.

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 discloses important behavioral traits beyond the annotations: "SPENDS CREDITS unless a report from the last 30 days already covers this company," the cached-result behavior, and the asynchronous execution model with immediate id/status return. These are exactly the non-obvious traits 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 tightly scoped sentences: what the tool does, the credit/caching caveat, and the expected async follow-up. There is no filler or repetition; each 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 one-parameter asynchronous initiation tool, the description is complete: it states the input, the outputs, the cost behavior, and the required polling step. The output schema exists, so return-value detail is not required here.

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

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

Schema description coverage is 100%, so the schema already fully explains companyUrl. The description reinforces that the URL is a LinkedIn company URL, but it does not add meaning beyond what the schema provides. 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 uses a specific verb and resource: "Start an Account Intelligence report for a company LinkedIn URL" and enumerates the outputs (firmographics, ICP verdict, buying committee). It also distinguishes itself from the polling sibling get_account_intelligence by stating that this call returns immediately and the other must be polled.

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: this is the initiating call, and it explicitly directs the agent to "poll get_account_intelligence until status is ready." It also explains the caching/credit condition that affects when the call is worthwhile, though it does not explicitly name alternatives such as run_person_intelligence or get_icp.

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 discloses important behavioral traits beyond the annotations: it spends credits, has a 30-day caching/short-circuit behavior, returns immediately, and requires polling for readiness. These details meaningfully inform an agent about cost and asynchronous behavior, and they do not contradict any annotation.

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 compact and front-loaded: it states the action first, then the critical cost caveat, then the response/polling behavior. Every sentence earns its place and there is no redundant 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 description covers the core workflow, cost implications, caching behavior, and the polling handoff to get_person_intelligence. With an output schema presentable to the agent, there is no missing information needed to correctly invoke this tool.

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

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

Schema description coverage is 100%, so the parameters are already fully documented in the schema. The description adds little to parameter semantics beyond restating that personUrl is a LinkedIn URL; that baseline of 3 is appropriate given 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 uses a specific verb ('Start') with a clear resource ('Person Intelligence snapshot') and target ('a person's LinkedIn URL'). It also distinguishes the tool from its sibling get_person_intelligence by describing the run-then-poll relationship, so an agent can tell them apart 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?

The description explicitly states the action triggers a snapshot and gives concrete guidance about when it should not be run ('unless a snapshot from the last 30 days already covers this person'). It also names the correct follow-up tool ('poll get_person_intelligence until status is "ready"'), which is strong usage direction.

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, but the description adds specific behavioral warnings: 'CHANGES WHERE YOUR DATA IS SENT when the routing or config is edited' and clarifies that pausing does not delete history. These go beyond the generic destructiveness hint, informing the agent of concrete side effects. No contradiction with annotations; the description enriches them.

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, front-loaded with the primary actions and then the crucial side-effect warning. No fluff or repetition. Every sentence adds distinct information – the first lists operations, the second warns about data routing and pause semantics. Highly efficient for an agent scanning for intent.

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 nested routing object and an output schema (provided), so return values are covered elsewhere. The description explains the key side effects (data routing changes, pause behavior) and implies the tool modifies an existing destination. It does not mention prerequisites like permissions or existence, but these are typically implied for update operations. Given the annotations and schema, the description is complete 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 100% – each parameter (id, name, routing, isActive) has a clear description. The tool description restates these actions ('Rename', 'pause or resume', 'change routing rule') without adding new syntax or format details. Since the schema already documents parameters thoroughly, the description adds minimal semantic value beyond a high-level summary. 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 clearly states the tool updates an existing destination by renaming, pausing/resuming, or changing routing. It distinguishes from sibling create_destination (which adds new) and list_destinations (which lists) by focusing on modifications. The verb 'update' plus the enumerated actions make the purpose 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 use for existing destinations by mentioning rename, pause/resume, and routing changes. It does not explicitly name alternatives like create_destination for new entries, but the context of modifying an existing destination is clear. Pausing behavior is explained as stopping delivery without deleting history, which provides usage context. However, it lacks explicit 'when not to use' or direct comparison to siblings.

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