Flux LinkedIn MCP

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

With no annotations, the description carries the full disclosure burden but does add genuinely useful economics: 'Free — costs 0 credits' and the fact that map_constellation runs per account afterwards. It omits duplicate handling, what happens to accounts that fail to resolve, and whether the call is idempotent — meaningful gaps for a write 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?

Three short sentences, front-loaded with the core action, then sequencing, then cost. No sentence is filler and nothing important is buried.

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

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

For a 2-parameter tool with fully documented schema, no annotations and no output schema, the description covers purpose, downstream effect and cost. The main missing piece is return behavior (count added, per-account failures), which the absence of an output schema leaves unexplained.

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%, including a description on the accounts array (1-500 per call), so the schema already documents both parameters. The description only clarifies that an account is 'a company you want to reach' and adds nothing about tier, employee_count, or linkedin_company_id — baseline 3 is appropriate.

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

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

States a specific verb (add) and specific resource (target companies into a Constellation campaign), which separates it from generic collection/segment tools in the sibling list. It stops short of explicitly contrasting with add_to_collection or add_to_segment, but the noun 'Constellation campaign' is distinctive enough for an agent to route correctly.

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?

'Each account is a company you want to reach; map_constellation is then run per-account' supplies the downstream workflow, letting an agent place this tool in a sequence. There are no explicit exclusions or prerequisites (e.g., when not to add an already-present account), so it falls shy 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?

With no annotations, the description carries the burden well: it discloses ownership requirement, behavior on existing members ('silently ignored', i.e. effectively idempotent), behavior across both collection types, and cost ('Free — costs 0 credits'). It omits failure/partial-success behavior and what the call returns.

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

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

Three dense sentences: the action first, then the type-dependent semantics, then the edge case and cost. No filler, nothing repeated from the schema.

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

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

For a two-parameter mutation with no annotations and no output schema, the description covers the important unknowns (ownership, idempotency, type-dependent effect, cost). The one gap is the absence of any indication of the response shape or error behavior, which an agent might want before bulk-adding up to 1000 posts.

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

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

Schema coverage is 100%, so post_ids (1-1000 UUIDs) and collection_id (from list_collections) are already documented in the schema. The description reinforces the post_id intent and adds no format, ordering, or dedup detail beyond that, so baseline 3 applies.

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

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

Specific verb ('Pin') plus resource ('one or more posts into a collection') with the scoping condition 'a collection you own — works on any collection type.' It clearly separates itself from nearby tools like add_to_segment and create_collection by naming the membership semantics.

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

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

Explicitly explains the manual-vs-smart distinction and that this is the *only* membership mechanism for manual collections, and it points at resolve_collection for seeing the union. It does not explicitly say when to prefer add_to_segment or create_collection instead, so it stops short of full alternative 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?

No annotations are supplied, so the description carries the full burden, and it does deliver two genuinely useful behavioral facts: duplicate members are silently ignored (idempotent, no error) and the operation is free at 0 credits. It still omits partial-failure behavior on large batches, auth requirements, and what happens when segment_id is unknown.

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

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

Two short sentences, front-loaded with the action and scope, then the two non-obvious facts (dedupe, cost). No filler, no restatement of the 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 simple two-parameter mutation with fully documented schema, the description covers the two traits an agent most needs: idempotency and zero cost. The gap is return behavior — there is no output schema, so the description should say what comes back (counts added vs. skipped) rather than leaving it unknown.

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% — person_ids documents the 1-1000 limit and segment_id points at list_segments — so the schema already does the work. The description only echoes 'by person_id' and adds no batch-size, format, or failure semantics beyond it.

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

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

States a specific verb and resource ("Add one or more people ... to an audience segment") with batch scope made explicit. It does not name the sibling it replaces (add_to_collection) or its inverse (remove_from_segment), so differentiation is inferred from the term 'segment' rather than stated.

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

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

Usage is implied by the verb and resource — you use it when you want people in a segment — but there is no explicit when/when-not, no mention of prerequisites (segment must exist, ids from list_segments or search results), and no routing to add_to_collection for the analogous collection 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?

With no annotations, the description carries the burden well: it discloses the sign-in prerequisite, the side effect (creates an own_profile stream pointing at the same posts), the free-plan scoping, and an explicit refusal condition. It stops short of saying what happens on paid plans or whether the created stream can be undone, but the mutation profile is largely covered.

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

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

Three compact sentences with the core action front-loaded, followed by prerequisite and failure condition. No wasted words and nothing buried.

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

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

For a one-parameter mutation tool with no annotations or output schema, the description covers prerequisite, side effect, scope, and refusal case. Minor gaps remain around reversibility and non-free-plan behavior, but an agent can call it correctly from this text.

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

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

Single parameter with 100% schema description coverage, so the schema already explains preview_id. The description reinforces that the id comes from preview_profile but adds no format or edge-case detail beyond that, so baseline 3 applies.

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

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

States a specific verb and resource ('Make a profile from preview_profile your own Flux dashboard') and names the downstream artifact ('own_profile stream'). It distinguishes itself from both preview_profile (inspection) and create_stream (generic stream creation) by tying the two together.

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?

Clear context of use: requires sign-in and it 'Refuses if you already track that profile' gives an explicit when-not condition. It does not explicitly say 'run preview_profile first to get a preview_id', though that is implied by the purpose sentence.

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

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

With no annotations, the description carries the full burden of behavioral disclosure for a create/mutation tool. It usefully states that the operation costs 0 credits, but it does not describe permissions, side effects, whether duplicates are allowed, or what the caller receives after creation.

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 tight sentences, front-loaded with the verb and resource. The second sentence adds useful domain context without padding, and the cost note is brief.

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

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

For a simple two-parameter create tool with full schema coverage, the description is sufficient to understand what is being created. However, with no output schema and no annotations, it leaves gaps around return behavior and mutation side effects.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description does not add meaningful semantics about the name or description fields beyond what the schema provides, 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 gives a specific verb and resource: 'Create a Constellation outreach campaign.' It also defines what a campaign is, grouping target accounts, people, and warm connections, which helps distinguish it conceptually from generic sibling resources such as collections or segments. It stops short of explicitly differentiating usage from those 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?

There is no guidance on when to use this tool versus alternatives like create_collection, create_segment, or create_stream. The only contextual note is that the operation is free, which is not a usage guideline.

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

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

With no annotations, the description does real work: it discloses the cost profile ('Free — costs 0 credits') and the key lifecycle distinction that smart collections are resolved on-demand rather than materialized. It omits failure modes such as duplicate-name behavior and whether type is immutable after creation.

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, zero filler. The core action leads, the mode branch follows, and the cost note is a short trailing clause that carries real decision value (credits are a tracked concern in this toolset).

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

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

Covers creation semantics, mode selection, predicate syntax, and cost for a 4-parameter tool with a nested object. The notable gap is that no output schema exists, yet the description never says what comes back (e.g. a collection id needed for add_to_collection or resolve_collection).

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

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

Schema coverage is 100%, so the baseline is 3; the description earns more by instantiating the opaque config object with a concrete predicate ({format:'video',min_likes:50}) and restating that config is required for smart collections. It adds no meaning for name or description, which the schema already covers.

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

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

States a specific verb and resource ('Create a new post collection') and immediately scopes it to the authenticated user. It also distinguishes the two creation modes and names the sibling tools (add_to_collection, resolve_collection) that operate on the result, so an agent can place it precisely in the collection family.

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

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

Gives clear branching guidance: use type='manual' when you intend to hand-curate via add_to_collection, use type='smart' with a config predicate for a dynamic collection. It stops short of stating exclusions, e.g. checking list_collections first or that type cannot be changed later, but the when-to-use path is unambiguous.

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?

No annotations are provided, so the description carries the full burden. It does disclose valuable behavior: the operation is free (0 credits), smart segments are resolved on-demand rather than materialized, and template defaults type to 'smart'. However it says nothing about authentication/permission requirements, uniqueness or naming conflicts, or what happens on invalid config keys.

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 that front-loads the core action and then walks the mode decision in reading order, with zero filler. Length is justified by the branching creation modes.

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?

Six parameters, nested object, two enums, and no output schema — the description covers how to construct the segment but never says what is returned (e.g., segment id needed for a follow-up add_to_segment call) or how auto_stream/source_stream_id relate to the other modes. Adequate, with a clear gap for a create tool lacking an output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine meaning beyond the schema: a concrete config example ({title_contains:'VP'}), the defaults interaction between template and type, and the rule that explicit config overrides template values on collision.

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

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

States a specific verb and resource ('Create a new audience segment') and immediately disambiguates the three creation modes (manual, smart, template). It also names the sibling tools that operate on the result (add_to_segment, resolve_segment), so an agent can distinguish it from related tools without opening a schema.

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

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

Explicitly routes the agent by mode: use type='manual' with add_to_segment to populate, type='smart' with a config predicate resolved by resolve_segment, or a template to pre-fill config. Each alternative is named alongside the condition that selects it.

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

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

With no annotations, the description carries the full burden, and it does disclose the important trait that scheduled runs consume credits and that per-type cost lives in get_cost_estimate, plus the own_profile carve-out. It says nothing about permissions/scopes, what is returned on success (e.g. a stream id the agent would need for pause_stream or get_stream_feed), or what happens on duplicate names.

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

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

Two sentences, front-loaded with the action and the resource scope, then the cost caveat and the exclusion. No filler; every clause carries information an agent needs before invoking.

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 7-parameter creation tool with a nested `params` object and no output schema, the combination of a solid description and fully documented schema covers what an agent needs to call it correctly. The remaining gap is the return value — an agent is not told that it gets back a stream handle to use with list_streams, pause_stream, or get_stream_feed.

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

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

Schema description coverage is 100% and the property descriptions are unusually rich — history_days and initial_max_pages are fully explained in the schema, not the description. The description only names the `type` values and the cost pointer, adding no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Create a new research stream') and enumerates the six stream types the tool supports, which maps directly to the `type` enum. It also distinguishes the resource from sibling creates (create_campaign, create_collection, create_segment) by naming exactly what a stream is.

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

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

Gives an explicit exclusion ('own_profile streams are not created here — they come from subscription checkout') and points to get_cost_estimate before committing, which is genuine pre-call guidance. It does not, however, contrast creating a stream with immediately running one (run_stream_now) or explain when a stream is preferable to a one-off search tool like search_posts.

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?

No annotations are provided, so the description carries the full burden, and it does most of it well: it discloses the cascade (stream_runs and auto-collection are removed), the preservation behavior (posts kept, stream_id set to NULL via ON DELETE SET NULL), and a hard restriction on own_profile streams. It omits whether the deletion is permanent/irreversible or what confirmation the call returns, which prevents a 5.

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

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

Three sentences, each carrying distinct information — action, data-preservation semantics, and the own_profile exclusion — with the core action front-loaded. No filler.

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

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

For a one-parameter destructive tool with no annotations and no output schema, the description covers the consequential unknowns an agent needs: what is destroyed, what survives, and what is off-limits. Only the irreversibility/response expectation is left unstated.

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

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

Schema coverage is 100% and the single parameter already documents 'Stream ID from list_streams'. The description adds no extra syntax or sourcing detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Delete a stream') and immediately scopes it to the stream and its stream_runs. It also distinguishes itself from stream-management siblings by ruling out own_profile streams, so an agent knows exactly what this operation targets.

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

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

Explicitly names the case where this tool must not be used ('own_profile streams cannot be deleted through this tool') and routes that case to Settings/billing. It lacks a mention of alternatives for ordinary streams (e.g., pause_stream when removal isn't intended), which keeps it short of a 5.

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

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

With no annotations, the description carries the burden and does well: it discloses the backend (pgvector cosine), that it reads only persisted local data (no LinkedIn pull), and that it is free. It doesn't describe the shape of returned results or ranking/tie-breaking, which is the remaining gap.

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

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

Front-loaded with what it does and on what data, then use-case, then alternatives, then scoping. Every sentence carries distinct information; no filler despite the length.

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

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

Covers mechanism, cost, data source, use case, alternatives, and scope resolution for a 4-param tool with no annotations and no output schema. The only omission is what the results look like (fields, ordering), which an agent might want before calling.

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

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

Schema coverage is 100%, so the baseline is 3, and the description goes beyond it by explaining the scoping model — profile_id scopes to a tracked profile, collection_id scopes to a collection, and specifying neither searches the whole library. That mutual-exclusivity/default behavior is not stated in the schema itself.

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 (find similar posts) plus the mechanism: pgvector cosine over the local post library. It explicitly contrasts with `search_posts` and `linkedin_post_search`, so an agent can pick it out of a large sibling set 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?

Gives the exact triggering condition ('a block of text — a draft, a paragraph, a competitor's post') and names the two alternatives with the conditions that select them (keyword search, fresh LinkedIn pull). Scoping options are also explained: profile_id, collection_id, or neither.

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

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

With no annotations, the description carries the full burden. It adds useful non-obvious context — that alerts are emitted by scheduled stream runs and that the call is free (0 credits) — and 'Return' implies a read-only operation. However, it does not disclose ordering, pagination behavior, or whether any read-state side effects occur.

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 four short sentences, front-loaded with the primary purpose, and every sentence adds useful context: what an alert is, how to filter read alerts, and the cost. There is no filler.

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

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

For a simple two-parameter read tool with 100% schema coverage this is mostly adequate, but with no output schema the description does not describe the return shape (e.g., alert fields, ordering), leaving an agent to guess what 'recent alerts' looks like in practice.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description clarifies `unread_only` in practical terms ('skip alerts the user has already marked read'), which matches the schema's semantics, but it adds little beyond that and says nothing about the `limit` parameter's range or default.

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 ('Return recent alerts') and defines what an alert is ('emitted whenever a scheduled stream run surfaces new items'), which helps distinguish it from get_stream_feed. However, it does not explicitly name or contrast with sibling tools, so sibling differentiation is only implicit.

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

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

It provides some usage context, such as passing `unread_only=true` to skip read alerts, and explains when alerts are emitted. But it offers no explicit when-to-use guidance versus alternatives like get_stream_feed, and no exclusions or prerequisites are stated.

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

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

With no annotations, the description carries the full burden and does well: 'Pure DB read — no LinkedIn pull, no credits charged' discloses both the side-effect profile and the cost model, which an agent cannot get from the schema. It omits return shape and whether results are truncated by limit, leaving a modest gap.

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

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

Three tight sentences: purpose first, then the relation semantics, then the cost/side-effect note. Every sentence carries information an agent needs and nothing is repeated from the schema verbatim.

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

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

For a read-only lookup with no output schema and no annotations, the description covers purpose, filter semantics, and cost. The remaining gap is what an 'engager' record contains and whether limit truncates silently, which matters for a tool returning up to 100 records.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond the schema by explaining the practical intent of 'alumni' for school-type companies. It says nothing extra about company_id vs company_url precedence, which is the one ambiguity an agent would hit.

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

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

States a specific verb and resource ('return engagers ... who have a position at that company') and scopes it to 'across your collected posts', which implicitly separates it from per-post siblings like get_post_engagers_by_company. It never names an alternative explicitly, so the differentiation is inferred rather than stated.

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

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

Gives real guidance on choosing the relation value, including the non-obvious tip that 'alumni' is most useful for page_type='SCHOOL' companies. It does not say when to prefer this tool over get_company_engagement_overlap or get_engager_position_history, so tool-level routing is left to inference.

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

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

With no annotations, the description carries the full burden. It does disclose two real behavioral traits: the operation is free (0 credits) and the output is a pre-aggregated summary rather than raw records. It does not say whether the result is a read-only snapshot, what period the stats cover, or what is returned for an empty campaign.

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 dense sentence front-loads the purpose and enumerates the returned metrics, followed by a short cost note. Every clause carries information; nothing is redundant with the 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?

There is no output schema, so the description must describe the return shape — and it does, naming the specific metrics and the two breakdown dimensions. The notable gap is the time window / scope of the stats, which an agent would need in order to interpret or compare results.

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

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

Schema description coverage is 100% for the single required campaign_id parameter, so the schema already documents it. The description adds the qualifier 'Constellation campaign', clarifying the ID's domain, which is a modest but real contribution over the schema's bare 'Campaign id'.

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

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

States a specific verb-and-resource ('Summary stats for a Constellation campaign') and enumerates exactly which metrics come back: target count, entry count, outreach volume, acceptance/reply rates, broken down by pool and composite-score tier. This is far more specific than the sibling list's other 'get_*' insight tools, though it never names a sibling it competes with.

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

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

Usage is implied by 'summary stats for a campaign' — an agent can infer this is the overview tool — but there is no explicit when-to-use/when-not clause and no routing to alternatives such as get_engagement_trends or get_cost_estimate. The 'Free — costs 0 credits' note nudges cost-based decisions but is not genuine usage guidance.

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

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

With no annotations, the description carries the full burden and does disclose the most decision-relevant trait: it is a pure DB read with no LinkedIn pull and no credits charged. It omits edge-case behavior (what happens when a company has no collected posts) and any auth/permission notes, keeping it below 5.

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

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

Three tight sentences: what it returns, why it matters, and its cost profile. Front-loaded with the core semantics and no filler.

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

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

Covers the prerequisite context that posts must be 'collected' and that results come from the local DB, which is important for a tool with zero annotations and no output schema. It stops short of clarifying the optional id/url inputs and the shape of a returned engager, the main remaining gap.

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

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

Schema coverage is 100%, so each parameter is already documented. The description adds nothing about the id-vs-url duality or that at least one identifier per company is needed (required list is empty), leaving a real ambiguity the schema does not resolve.

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

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

States a specific verb and resource: return engagers who engaged with BOTH of two companies' posts. The 'BOTH' intersection semantics implicitly separate it from get_post_engagers_by_company and get_alumni_engagers, though no sibling is named explicitly.

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

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

Provides an implied use case ('Cross-account intelligence — finds people interested in multiple targets simultaneously') but gives no explicit when-to-use/when-not or a named alternative for single-company lookups. The agent must infer routing from the intersection framing.

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

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

With no annotations, the description carries the burden well: it discloses the fallback rule for unregistered tools (assumed cost 0), that the call itself is free, and the exact return payload shape. It doesn't mention auth requirements or limits on how many tools can be estimated.

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

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

Three tight sentences: what it returns, the second input mode with examples, and the output/fallback behavior. Zero filler and the core purpose 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?

Covers purpose, both input modes, return fields, and the unknown-tool fallback, which is thorough for a no-output-schema tool. Minor gaps: the reserved 'params' object and the semantics of 'sufficient'/'balance' are not explained.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds value beyond the schema by enumerating all six valid stream type strings (external_profile, company, topic, person_interests, hiring_signals, ad_watch), whereas the schema only gives 'e.g. external_profile'. The unused 'params' object is not discussed.

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

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

States a specific verb and resource ('Given an MCP tool name, return its credit cost') plus a second accepted input mode (stream types). It is clearly distinguishable from siblings like get_credit_balance (which presumably reports current balance) and get_usage_history.

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

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

Explains the motivating use case ('preview an action before running it') and ties the stream-type mode to create_stream / run_stream_now. It never states when to use get_credit_balance or get_usage_history instead, so the routing guidance is clear but not exhaustive.

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

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

With no annotations, the description carries the full behavioral burden. It does add one real behavioral fact — 'Free.', i.e. the call costs no credits — and scopes the result to the authenticated user, which are valuable disclosures. It does not address auth failure behavior, whether the period boundary is timezone-dependent, or units of the balance, so the disclosure is only partial.

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 return payload, with the cost note last. No filler, no restatement of the 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?

No output schema exists, so the description must carry the return shape — and it does, naming all three returned values. It falls slightly short for a billing-oriented tool by omitting units, whether the balance can go negative, and the reset semantics of the period.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly says nothing about inputs, which matches the empty schema.

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

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

Names a specific verb+resource ('Return the authenticated user's current credit balance') and enumerates exactly which values come back (balance, monthly allocation, credits used this period). It doesn't explicitly contrast itself with adjacent cost/usage siblings like get_usage_history or get_cost_estimate, so an agent must infer the split, but the purpose itself is unambiguous.

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

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

No explicit when-to-use or when-not-to-use statement, and no sibling is named as an alternative. The trailing 'Free.' implies this is a safe, zero-cost check, which nudges the agent toward calling it before spending actions, but that is inference rather than 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that the call is free, that exactly one identifier must be supplied, and that non-campaign forms work without a Constellation campaign, but it does not cover return structure, error behavior, or other operational details.

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

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

Two short paragraphs, front-loaded with purpose and usage, then identifier rules. Every sentence adds useful information without 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?

For a tool with no annotations and no output schema, the description explains the return content, cost, identifier constraints, and campaign independence. It is nearly complete, though it could say more about the exact response shape or failure modes.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: the three identifiers are mutually exclusive, target_id is campaign-scoped, person_id is the canonical people row, and linkedin_url is auto-resolved. It also clarifies that non-campaign identifiers work without a campaign.

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

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

States a specific verb and resource: returns one person's recent posts relevant to the caller's posting topics, plus suggested talking points. The use case ('before a warm comment or DM') and output shape distinguish it from generic profile or post-listing 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?

Gives a clear usage context ('Use before a warm comment or DM') and explains how to select the person via exactly one identifier. It does not explicitly name when not to use it or point to a specific alternative sibling, so it falls short of full when/when-not guidance.

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

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

With no annotations, the description carries the full burden and does well: it declares 'Pure DB read — no LinkedIn pull, no credits charged', covering both safety and cost implications, and discloses the `_unknown` bucketing edge case. It omits anything about permissions or result size/pagination, keeping it from a 5.

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

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

Four tight sentences, each doing distinct work: purpose, pivot source, depth semantics, unknown handling, and cost/safety. The most decision-critical information (what the tool produces) is front-loaded with zero filler.

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

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

There is no output schema, but the description conveys the return shape well ('histogram' with sample company names attached per row) and all four parameters are documented in the schema. For a read-only aggregation tool with no annotations, only the lack of permission/scope context and row-limit behavior leaves a gap.

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

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

Schema coverage is 100%, so the baseline is 3, and most of the description's depth explanation duplicates the schema's own 'depth' documentation almost verbatim. The `sample_companies_per_bucket` parameter is never mentioned in the description beyond the vague 'sample company names... per industry row'.

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?

It opens with a specific verb+resource ('Histogram of engagers' companies grouped by industry') and names the exact data source (companies.industry_hierarchy), which clearly separates it from list-style siblings like get_post_engagers_by_company. It stops short of explicitly naming the sibling it is not, so the differentiation is inferential rather than stated.

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

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

The description explains how the depth parameter changes the bucketing and how missing data is handled, which implicitly guides usage. But it never says when to reach for this tool instead of get_post_engagers_by_company, get_company_engagement_overlap, or get_engagement_trends, and gives no prerequisites or 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?

With no annotations provided, the description carries the disclosure burden and does well: it reveals that buckets are gap-filled, that rolling averages are computed, that trend direction is returned, and exactly what each bucket contains (avg engagement, likes, comments, shares, conversation rate). It omits auth/permission requirements and pagination/limit behavior, keeping it from a 5.

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

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

Three sentences, front-loaded with the core capability, then output contents, then usage. The final sentence about the scope parameter is somewhat redundant with the schema but is short and earns its place as a hint.

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 appropriately explains the returned bucket contents and computation behavior (gap-filling, rolling averages, trend direction). Combined with the fully documented input schema, an agent has enough to call it correctly; only auth and pagination context are 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 schema already documents all six parameters including scope, dates, granularity, and rolling_window defaults. The description only restates that scope should be a post_collections.id, adding no new semantic detail beyond the schema.

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

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

States a specific verb and resource ('Get engagement time series for a profile') and immediately specifies the distinctive output features: gap-filled buckets, rolling averages, and trend direction. This clearly distinguishes it from siblings like get_engagement_brief or get_posting_insights.

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?

Says it is 'useful for understanding whether engagement is growing or declining' and explains the scope parameter's purpose, but never states when to prefer this over alternatives such as get_engagement_brief or get_posting_insights, nor any exclusions or prerequisites.

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

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

With no annotations present, the description carries the full burden and handles the most expensive unknowns well: 'pure DB read — no LinkedIn pull, no credits charged' removes cost risk, and the framing as a position-graph read sets expectations. It does not say what happens when the engagement gate is unmet (empty result vs. error) or whether the timeline is truncated.

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

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

Three short sentences, each load-bearing: what it returns, the eligibility gate, the sort order, and the cost profile. No filler and the core purpose 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 two-param read with no output schema, the description covers the essentials — source, eligibility, ordering, and cost. The remaining gap is error/empty-state behavior and the identifier-selection rule, minor but relevant given both params are optional.

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

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

Schema coverage is 100%, so both parameters are documented in the schema and the baseline applies. The description adds nothing about the person_id/linkedin_url relationship — with zero required parameters, the agent gets no guidance on whether one identifier is mandatory or which takes precedence.

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

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

The description names a specific verb and resource — 'return a person's full employment timeline from the position graph' — which is far more precise than the title 'Engager Position History'. It does not name a sibling it replaces or contrasts with (e.g., get_profile_summary, traverse_graph), so the agent must infer boundaries from the sibling list 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?

It states a concrete eligibility condition: the person must have engaged on at least one collected post. That is a real gate an agent needs before calling. It stops short of 5 because it never says what to do when the gate fails or which alternative to use for non-engagers.

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

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

With no annotations, the description proactively supplies the key behavioral facts an agent cares about: it is a pure DB read, performs no LinkedIn pull, and charges no credits, plus the hard 3-hop ceiling. It does not cover failure modes (no path found, missing identifier), which keeps it from a 5.

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

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

Four short clauses, front-loaded with the purpose, and each adds distinct information: mechanism, edge types, hop limit, and cost/safety. Zero filler and nothing repeated from the schema.

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

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

No output schema and no annotations, so the description must carry the load; it covers mechanism, safety, cost, and scope well. Remaining gaps are what a returned path looks like and the requirement to supply one of the two target identifiers, which the agent is left to infer.

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 limit, max_hops, and both target identifiers; the description only reinforces the hop cap ('up to 3 hops'). It adds nothing about the important ambiguity that target_person_id and target_linkedin_url are both optional yet at least one is presumably needed.

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

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

States a specific verb and resource — 'find the shortest warm-intro path through your engager network' — plus the edge types traversed (coworker, alumni) and the hop cap. This is enough to tell it apart from graph-ish siblings such as traverse_graph or map_constellation, though it never names an alternative explicitly.

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

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

Usage is implied: 'Given a target person' frames the scenario, and the network/mutual-connection premise makes the intent reasonably clear. But there is no explicit when-to-use versus when-not (e.g., LinkedIn pull vs. cached network, or when the target has no path), so the agent must infer the boundary.

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

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

No annotations exist, so the description must carry the behavioral load and it does well: it discloses per-scope return content (composite_score, pool, recommended_action, prior outreach_log entries), states that segment/url modes omit composite_score, and declares the operation is free (0 credits). It stops short of describing auth requirements or what happens on zero/multiple scope input.

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 lead sentence plus three tight bullets, with the mutual-exclusivity constraint front-loaded and the cost note last. Every clause adds information; nothing restates the 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?

With no output schema and no annotations, the description fills the gap by explaining what each scope returns and how ranking differs, which is what an agent needs to choose and call correctly. Response envelope shape, pagination/truncation behavior, and error semantics when scope selection is invalid remain undocumented.

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

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

Schema coverage is 100%, so 3 would be the baseline; the description adds real meaning by explaining that segment_id and linkedin_urls rank by engagement count against tracked profiles' posts while campaign_id uses full Constellation scoring, which the schema does not convey. The mutual-exclusivity rule across the three id parameters is also only in the description.

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

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

States a specific verb and resource ('Return a prioritized outreach queue') and immediately disambiguates three distinct scopes, each with its own ranking model and output fields. An agent can tell which mode fits its data 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 'Provide *exactly one* of three scopes' constraint is explicit, and each bullet explains what that scope means and what it returns, which effectively encodes when to use it. It does not name sibling tools (e.g. get_outreach_path, list_segments) that an agent might also consider, so it falls short of a full when/when-not/alternatives statement.

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

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

With no annotations, the description carries the burden well: it discloses the join path (person_positions with is_current=true), the `_unknown_company` bucketing for engagers lacking a current company, and that no LinkedIn pull or credits occur. It stops short of describing pagination or the exact row shape, but the key behavioral traits are covered.

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

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

Four tight sentences, front-loaded with the core action and scope, then the join detail, the cost/safety note, and the edge-case bucketing. No filler and every sentence adds information.

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

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

No output schema and no annotations, so the description must convey the return shape, which it does (companies ranked by engager count, with sample engagers implied by top_engagers_per_company). It is nearly complete, though it could say more about ordering ties or the response envelope.

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

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

Schema coverage is 100%, so all five parameters are already documented, setting the baseline at 3. The description adds only marginal meaning beyond the schema — that industry_urn narrows to a single industry and that post_url/post_id are interchangeable inputs — without explaining limit or top_engagers_per_company behavior.

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

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

States a specific verb and resource ('return the companies whose people engaged') plus the ranking rule, and the input ('LinkedIn post URL or id'). It is clearly distinguishable from siblings like get_post_set_engagers and get_alumni_engagers, which target different engager groupings.

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

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

Gives context for when the tool applies (post URL or id, optional industry narrowing) and notes it is a pure DB read with no credits charged, which is a useful selection signal. However, it never names an alternative sibling or states when NOT to use it, so the agent must infer the choice between this and get_post_set_engagers/get_alumni_engagers.

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

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

With no annotations, the description carries the full burden. It does add real behavioral value: metrics are relative to the user's own baseline, and every bucket carries a full metric breakdown. But it omits cost/latency implications, which matter given the presence of get_cost_estimate/get_credit_balance siblings and a preview_ variant that implies this is the expensive call.

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

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

Front-loaded with the payoff (optimal posting patterns) and the four buckets, then the metric semantics, then the optional scope. Four sentences, all mostly earning their place; the scope sentence duplicates schema content, which is the only waste.

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 and no annotations, so the description must stand in for both. It does a fair job describing returned buckets and metric definitions, but leaves the default time window and any cost/side-effect profile unstated – a moderate gap for an analytics call that may consume credits.

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 scope sentence restates the schema's meaning slightly more operationally ('recompute the patterns against a specific collection'), but date_from/date_to are ignored entirely – the description never says whether patterns default to all-time or a trailing window, which is the one genuinely ambiguous parameter behavior.

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

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

Specific verb+resource plus an enumeration of what the response contains (best day, best hour, format breakdown, character-length sweet spot), which clearly separates it from generic siblings like get_profile_summary or get_engagement_trends. It never names the closest sibling, preview_posting_insights, which reads as the preview counterpart to this tool, so the differentiation is incomplete.

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

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

Usage is only implied – the description says what patterns you get, not when to reach for this over preview_posting_insights, get_topic_insights, or get_engagement_trends. The one explicit conditional it does give is for `scope` (recompute against a specific collection), which is helpful but narrow.

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

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

With no annotations, the description carries the full burden and does well: it discloses the data source (local library, no live pull), that it is free, that results are paginated, and that returned data includes full metrics and text. It omits specifics on return shape and any rate/permission constraints, keeping it just short of a 5.

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

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

Front-loads the core purpose, then adds filtering scope, pagination, and alternatives in a tight sequence. Every sentence — including the cost/data-source note and the sibling routing — carries distinct, useful information.

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

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

For an 11-param tool with no output schema and no annotations, the description covers data source, cost, pagination, filter axes, scope semantics, and alternatives. The only gap is a fuller picture of the returned 'full metrics' payload, but overall it is complete enough to call correctly.

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

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

Schema coverage is 100%, so the schema already documents most fields. The description still adds conceptual value: it explains scope as a post_collections.id restricted to a collection and gives concrete examples (external profile, topic stream, curated set), and summarizes the filter axes (date range, post type, min engagement, text) that map to the params.

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

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

States a specific verb+resource ('List a tracked profile's persisted posts') and immediately scopes it to the local library with 'no LinkedIn pull, free'. It distinguishes itself from both search_posts and linkedin_profile_posts by name.

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

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

Gives an explicit entry condition ('when the caller already has a profile_id') and names two alternatives with their selecting conditions: search_posts for keyword/semantic search, linkedin_profile_posts for fresh pulls. Nothing is left to inference.

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

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

With no annotations, the description carries the full burden and does well: it discloses the freshness skip, that enrichment is limited to never-seen people up to max_enrich, and an explicit cost model (2 credits/post, 3/person, cached posts free). It omits permission/auth requirements and does not describe the return shape, which matters because there is no output schema.

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 dense sentences, front-loaded with the what, then the freshness/enrichment mechanics, then the cost. Every clause carries decision-relevant information (scope, cost, caching) with no filler.

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

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

For a 6-parameter aggregation tool with no annotations and no output schema, the description covers behavior, caching, and billing well. The remaining gaps are the return shape (what fields a deduped engager carries) and what happens when profile_id and collection_id are both or neither supplied.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by tying max_enrich to the enrichment pass and its 3-credit cost, and by explaining that freshness_days drives both skipping and free cached reads. It leaves the profile_id/collection_id relationship (mutual exclusivity, behavior if neither is given) unexplained.

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

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

States a specific verb and resource ('Return the consolidated, deduped people who reacted to or commented on a SET of posts') and immediately scopes it to two input modes, profile_id or collection_id. The emphasis on SET plus 'consolidated, deduped' distinguishes it from the single-post siblings like linkedin_post_reactions and linkedin_post_comments without naming them.

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

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

The description gives clear selection context: use profile_id for one tracked profile's stored posts or collection_id for a collection's posts, and it explains the freshness gate that governs whether a call does work. It does not explicitly say the two ids are mutually exclusive or when to prefer this over get_post_engagers_by_company, so it stops short of full when/when-not guidance.

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

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

No annotations were provided, so the description must carry the full behavioral burden. It does disclose the shape of the response (the specific KPI metrics), which matters because no output schema exists. However, it says nothing about read-only semantics, credit consumption, caching, or authorization requirements, which are exactly the traits annotations would normally cover.

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

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

It is a single dense sentence with the resource and the metric list front-loaded and no filler. Every clause earns its place by naming a specific returned metric.

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 tool with no output schema, the description is nearly complete: it enumerates the returned KPIs so the agent can judge relevance without calling it. The remaining gap is that it doesn't position the tool against the several sibling analytics tools (engagement trends, posting insights, profile preview).

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 single parameter has 100% schema description coverage and is already documented as a 'Tracked profile ID from list_profiles.' The description adds nothing about the parameter, which is fine here because the schema covers it, but it provides no added meaning.

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

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

The definition pairs a specific verb ('Get KPI summary') with a specific resource ('tracked profile') and enumerates the metrics returned (posts, engagement breakdown, posts/week, trend, top format, goal status). An agent knows exactly what this returns, but nothing distinguishes it from siblings like preview_profile, get_posting_insights, or get_engagement_trends.

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 no explicit when-to-use or when-not-to-use guidance, and names no alternative. The closest thing to routing information is the schema's note that profile_id comes from list_profiles, which implies a two-step workflow but never states it in the description itself.

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?

No annotations are provided, so the description carries the full disclosure burden. It usefully adds the ordering guarantee ('newest first by published_at') and the fact that results come from the library after the stream has run on its schedule, but it says nothing about permissions, rate limits, or how much of a post is returned.

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

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

Two tight sentences, zero filler, with the scoping and ordering constraints front-loaded before the usage hint. Nothing needs trimming.

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

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

For a two-parameter read tool with a fully described schema, the definition covers what matters: source, ordering, and the stream types it applies to. The main remaining gap is that with no output schema, it doesn't hint at what a returned post contains or whether results are limited to what already accumulated before the last stream run.

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

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

Schema description coverage is 100%, so both parameters are already documented, including that stream_id comes from list_streams and limit caps at 50. The description adds no further parameter meaning, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('Return the most recent posts a stream has collected into the library') plus a defined scope: scoped to a stream, ordered newest first by published_at. That distinguishes it from the broader get_posts/search_posts siblings, though it never names those alternatives directly.

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 offers a use case ('browse what a topic / external profile / person_interests / company stream has surfaced on its schedule'), which implies when to reach for it. But it gives no when-not guidance and never points to search_posts or get_posts for ad-hoc or cross-stream retrieval, leaving the choice between feed browsing and search entirely to inference.

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

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

With no annotations, the description carries the full burden and does well: it discloses that this is a pure DB read, that no LinkedIn pull occurs, and that no credits are charged — exactly the cost/side-effect facts an agent needs. It also explains how the warmth score is derived (engagement count, comment signal, recency). It stops short of stating behavior for a missing/unknown person or how person_id and linkedin_url are resolved when both are omitted.

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

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

Three tight sentences: what it summarizes, how the score is computed, and the cost/side-effect profile. The most decision-relevant facts (scope and no-credits) are front-loaded with no filler.

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

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

There is no output schema, and the description compensates by enumerating the returned evidence categories and the computed score, which is sufficient for an agent to know what comes back. The remaining gap is the unresolved question of which identifier to supply when both person_id and linkedin_url are optional.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema and the baseline is 3. The description adds only the notion of recency feeding the score, not any clarification of days_back bounds or the person_id vs. linkedin_url precedence — a real ambiguity given zero required 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 names a specific verb (summarize) and a precise resource (engagement evidence between a target person and your collected posts), then enumerates the evidence types and the derived warmth score. It is unambiguous what the tool produces, but it never names or contrasts with the close sibling get_engagement_brief, so an agent must infer the distinction.

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?

"For a target person" implies the usage context (per-person analysis) and the closing sentence implies it is the cheap, no-credit option, but there is no explicit when-to-use/when-not guidance and no mention of get_engagement_brief or get_engagement_trends as alternatives. Usage is inferable rather than stated.

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

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

With no annotations, the description carries the full burden and does some real work: it discloses ranking basis (post count), the engagement metrics attached, and that computation happens server-side mirroring the dashboard chart. It is silent on cost/credits (relevant given siblings like get_cost_estimate and get_credit_balance), on whether this is strictly read-only, and on performance or limits for large profiles.

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, front-loaded with the purpose before the return shape and the scoping note; every clause is substantive. The final sentence largely duplicates the schema's `scope` description, a small 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?

There is no output schema, and the description compensates well by naming the returned fields and their ranking. Parameters are covered by the schema. It stops short of stating default time-window behavior for date_from/date_to or credit implications, which is a modest gap for an analytics call on 6 parameters.

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

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

Schema description coverage is 100%, so all six parameters are already documented; the description only echoes `scope` as a post_collections.id and the notion of 'top N'. It adds no clarification about bigram defaults, date-range behavior, or the interaction between n and the two lists, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Surface the most-frequent topics in a profile's posts, with engagement context,' and enumerates the return shape (unigrams, optional bigrams, avg_engagement, vs_baseline, sample_post_url). It does not explicitly differentiate itself from the nearby siblings get_posting_insights and preview_posting_insights, which is the only thing keeping it off a 5.

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

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

The only guidance is 'Pass `scope` (a post_collections.id) to scope the analysis to a collection,' which restates the schema. There is no statement of when to prefer this over get_posting_insights or preview_posting_insights, and no prerequisites such as needing a profile_id from list_profiles (that hint lives only in the schema).

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

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

With no annotations, the description carries the full burden and does disclose two real traits: results are paginated and the call is free (no credit charge). It omits sort order, what 'recent' means numerically, whether pagination is offset- or cursor-based, and any auth scope detail beyond 'authenticated user'.

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 terse fragments, front-loaded with the resource and followed by filters, pagination, and cost. Every clause adds a distinct fact and there is no filler.

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

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

For a five-parameter read tool with no annotations and no output schema, the description covers scope and pagination but says nothing about the shape of a ledger entry (amount, reason, tool, timestamp) or ordering. An agent knows how to call it but not what it will get back.

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 limit, reason enum, date bounds, and tool_name. The description only restates the filter dimensions at a high level without adding format or semantics, so it cannot exceed the baseline.

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

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

States a specific verb and resource: returns credit_ledger transactions scoped to the authenticated user. An agent can distinguish it from balance-checking tools like get_credit_balance, though the description never explicitly names that distinction.

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

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

Usage is implied rather than stated — filtering by tool/reason/date suggests an audit or spend-review use case, and 'Free' signals it can be called without credit cost, a useful nudge against cost-related siblings. But there is no explicit when-to-use or when-not-to-use guidance and no named alternative such as get_credit_balance.

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?

No annotations, so the description carries the full burden — and it does disclose a critical behavioral fact that nothing else states at the tool level: 10 credits per call. It stops there, saying nothing about auth requirements, result limits, or result shape. The cache-vs-live tradeoff is documented, but only inside the schema's refresh property rather than in the description.

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

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

Three short sentences, zero padding, purpose first and the cost constraint surfaced immediately rather than buried. Each sentence contributes something an agent would act on.

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?

Adequate for a 3-optional-parameter search with a fully documented schema and no output schema, but thin given zero annotation coverage: no statement of what results contain, whether results are paginated or capped, or how company/keywords interact when both are supplied.

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%, including the important nuance that refresh=false returns cached results free while refresh=true re-runs live at cost. The description adds no parameter meaning beyond that, so the schema does all the work — baseline 3 applies.

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

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

States a specific verb and resource ('Search the LinkedIn ad library') plus a concrete use case (competitor ad creative and messaging). What's missing is differentiation from the many related lookup siblings (linkedin_company_posts, linkedin_post_search, linkedin_company_search), so an agent can't tell from the description alone why it would pick this over those.

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?

'Useful for tracking competitor ad creative and messaging' implies the scenario but gives no explicit when-to-use/when-not framing and names no alternatives. With dozens of LinkedIn search siblings available, a routing sentence would have real value here.

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

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

With no annotations, the description carries the full burden and does well: it discloses metered cost (5 credits per page of 50, capped at 250 posts, charged only for pages actually fetched) and a real side effect — results persist into the post library with source_type='external' and a linked linkedin_profiles row. It omits auth requirements and whether re-fetching duplicates stored rows, which keeps it below 5.

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

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

Three compact sentences with zero waste: purpose first, then cost, then the persistence side effect. Every clause carries information an agent would otherwise have to guess.

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

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

Covers scope, pricing, and the write side effect for a tool with no annotations and no output schema. The remaining gap is the return shape — what fields a post carries and how 'recent' is bounded — which is not covered anywhere else since there is no output schema.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema, including refresh's cache semantics and max_posts' range. The description only reinforces the 250-post ceiling and per-page credit pricing, adding little beyond the structured fields — the baseline 3 applies.

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

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

States a specific verb and resource — 'Fetch recent posts from a LinkedIn company page' — which cleanly separates it from the profile-oriented sibling (linkedin_profile_posts) and from linkedin_post_search. It does not explicitly name an alternative tool, so it falls just short of the top mark.

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 company-page scope implies when this tool applies, and the credit model gives an agent enough to weigh whether a fetch is worth it. However, there is no explicit 'use X instead when...' routing and no stated prerequisites (e.g. that a linkedin_url must resolve to a company page).

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

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

With no annotations present, the description must carry the full behavioral burden. It does disclose cost ("5 credits per call") and return shape ("a single page"), which are valuable, but it omits permission requirements, rate limits, page size, and how to retrieve subsequent pages; the cost detail also partially overlaps with the refresh parameter's schema description.

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 three short sentences, front-loaded with the action and resource, followed by filters, cost, and return shape. Every sentence earns its place with no repetition or fluff.

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 search tool with fully documented parameters, the description covers purpose, filter dimensions, cost, and return shape. The main remaining gap is pagination behavior beyond "a single page," but the definition is otherwise complete enough to select and call 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%, so the schema already documents all four parameters, including the refresh/cache behavior and industryId ID format. The description adds no syntax, format, or default-value guidance beyond what the schema provides, making baseline 3 appropriate.

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

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

The description states a specific verb and resource ("Search LinkedIn companies") and names the filter dimensions, so an agent knows exactly what the tool does. It is distinguishable from resource-specific siblings like linkedin_people_search and linkedin_job_search, but it does not explicitly name or contrast any sibling.

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

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

There is no guidance on when to use this tool versus alternatives such as linkedin_people_search or linkedin_ad_search, and no exclusions or prerequisites are stated. The filter list implies usage but does not tell the agent when this is the right choice.

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

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

With no annotations, the description carries full burden, and it does disclose the credit cost, which is a meaningful behavioral trait. However, it omits result shape, pagination, and whether results are live or cached. Worse, the flat claim 'Costs 5 credits per call' slightly conflicts with the schema's note that cached results are returned free unless refresh is true.

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

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

Two short sentences, front-loaded with the purpose and immediately followed by the value proposition and cost. No filler, though the cost sentence would have earned more if qualified with the cache caveat.

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 at least hint at what a result looks like and how many are returned; it does neither. The rich parameter schema covers inputs well, but for a paid search call the description leaves the agent guessing about result shape and cost conditions.

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 explains keywords, location, companyId with its ID-resolution caveat, sortBy, postedLimit, and refresh semantics. The description adds nothing beyond the mandatory-parameter baseline, which is acceptable but earns no extra credit.

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

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

States a specific verb and resource ('Search LinkedIn job postings'), which distinguishes it from the many linkedin_* siblings that cover people, companies, posts, and ads. It stops short of naming or contrasting any specific sibling, so an agent must infer the split from the resource noun 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?

'Useful for tracking hiring signals at target companies' gives one motivating use case but no when-not conditions, no prerequisites, and no named alternatives (e.g. linkedin_company_posts vs this for headcount signals). Usage has to be inferred from the resource name.

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

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

With no annotations, the description carries the full disclosure burden. To its credit it surfaces the two most consequential traits: a cost of 5 credits per call and page-bounded results ('single page of matching profiles'). It says nothing about caching behavior (left to the refresh param schema), rate limits, authentication, or how to page beyond the first result set.

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

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

Three short sentences, zero filler, with the core action front-loaded and cost surfaced early. Every sentence contributes distinct information.

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

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

All five params are optional and there is no output schema or annotations, so the description needs to stand on its own. It covers cost, result shape, and filters adequately, but omits that zero filters still incurs 5 credits and gives no hint about result volume or how to continue past page one.

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 every parameter including the non-obvious refresh cache tradeoff. The description only restates the filter names already present in the schema and adds no syntax, matching-behavior, or multi-filter combination guidance beyond it.

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

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

States a specific verb and resource ('Search LinkedIn people') and enumerates the available filter dimensions, which naturally separates it from siblings like linkedin_company_search, linkedin_job_search, and linkedin_post_search. It never names an alternative explicitly, so the differentiation is implied by the resource noun rather than stated.

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

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

The description lists the filter axes (company, title, location, keywords) which implies how the tool is used, but gives no when-to-use guidance, no prerequisites, and no exclusions. Nothing tells the agent when to prefer linkedin_profile_info or traverse_graph over this search.

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

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

No annotations exist, so the description bears the full behavioral burden. It does disclose two important traits: a 5-credit cost and that each comment is persisted to post_engagements, which is genuinely non-obvious side-effect information. However, it says 'costs 5 credits per call' without noting the cache path that makes repeat calls free, and omits any auth or rate-limit context.

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

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

Three short sentences with no filler, and the core capability is stated first. The cost statement earns its place but is slightly imprecise relative to the refresh parameter, which is the only real deduction.

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

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

For a two-parameter read tool with no output schema and no annotations, the description covers purpose, cost and a persistence side effect. The notable gap is the absence of any mention of result limits or pagination, so an agent cannot tell how many comments come back.

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

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

Schema description coverage is 100%, so both post_url and refresh are fully documented in the schema, establishing the baseline of 3. The description adds no parameter-level detail beyond the ambiguous per-call credit claim, which actually conflicts slightly with the schema's note that cached results are free.

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

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

The description names a specific verb and resource: fetching the commenters on a single LinkedIn post plus their comment text. That is clearly distinct from siblings like linkedin_post_reactions (reactions) and linkedin_profile_comments (comments tied to a profile), though no sibling is named explicitly.

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

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

The word 'single' implies the tool takes one post rather than a set, which is useful scoping. But the description never states when to prefer this over linkedin_post_reactions or linkedin_profile_comments, and gives no exclusions or prerequisites.

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

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

With no annotations, the description carries the burden and usefully discloses that each call costs 5 credits and that engagers are persisted to the post_engagements graph. It does not cover rate limits, pagination, or full return-shape details, but the cost and persistence side effect are significant behavioral context beyond the schema.

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 three tight sentences, front-loaded with the tool's purpose, followed by cost and persistence behavior. Every sentence adds practical information without repetition or 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?

For a two-parameter fetch tool with no output schema and no annotations, the description gives enough context to select and invoke it: what it returns, what it costs, and that results are persisted. It could still mention pagination or return limits, but the core invocation context is present.

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

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

Schema description coverage is 100%, so the schema already documents both post_url and refresh. The description adds the notion of a 'single LinkedIn post' but does not elaborate on parameter formats or the refresh/cache behavior beyond what the schema provides.

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

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

The description uses a specific verb and resource: 'Fetch the people who reacted to a single LinkedIn post.' It clearly scopes the tool to a single post, which distinguishes it from sibling tools like linkedin_profile_reactions and linkedin_post_comments without needing to name them.

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

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

The description implies the tool's use case by stating it fetches reactors on a single post, but it does not explicitly say when to use this versus linkedin_profile_reactions, linkedin_post_comments, or other engagement tools. No exclusions or alternative-routing guidance 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?

With no annotations, the description carries the full disclosure burden. It usefully states 'Costs 5 credits per call' and 'Returns a single page of matching posts,' which adds real behavioral context beyond the schema. However, it omits pagination mechanics, rate limits, authorization needs, and what a 'single page' contains, leaving material gaps for an unannotated search tool.

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

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

Three short sentences, front-loaded with the core action and followed by cost and result-shape notes. Every sentence earns its place and there is no filler.

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

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

There is no output schema and no annotations, so the description should carry more of the return-value and operational context. It says results are a 'single page' but does not explain page size, how to retrieve subsequent pages, or what fields matching posts include. Given the nested filters and paginated search behavior, this is adequate but incomplete.

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 query, filters, and refresh parameters are already well documented in the schema, including the cache-bypass behavior of refresh. The description adds no parameter-level detail beyond implying keyword input, so the 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 gives a specific verb and resource: 'Search LinkedIn posts by keyword.' An agent can immediately tell this is a keyword search over LinkedIn posts. However, it does not distinguish the tool from several close siblings such as search_posts, find_similar_posts, linkedin_company_posts, and linkedin_profile_posts.

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 states a credit cost but gives no guidance on when to use this tool versus search_posts, find_similar_posts, or any of the other post-related siblings. There are no exclusions, prerequisites, or alternative-routing hints beyond the bare keyword-search framing.

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?

No annotations, so the description carries the full burden. It usefully discloses the 5-credit cost per call and that results are cached (from the schema), implying a read operation, but says nothing about how many posts are returned, the recency window, or whether the result includes the comment text.

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

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

Two tight sentences: purpose first, then value and cost. Nothing wasted, nothing buried.

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

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

For a 2-parameter, no-annotation, no-output-schema tool, the description covers purpose and cost but leaves the agent guessing about result volume, recency window, and return contents — meaningful gaps given nothing else describes them.

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

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

Schema coverage is 100% and both parameters are documented there, including the refresh cache-bypass behavior. The description adds no parameter-level detail, so baseline 3 applies.

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

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

States a specific verb and resource: fetches recent posts a LinkedIn person has commented on, which implicitly separates it from linkedin_profile_posts (their own posts) and linkedin_profile_reactions. Clear, though it never explicitly names those 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?

"Useful for inferring interests and conversation partners" gives a use case, but there is no explicit when-to-use guidance versus linkedin_profile_posts, linkedin_post_comments, or get_profile_summary, and no exclusions or prerequisites.

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

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

Since there are no annotations, the description carries the full burden and does an excellent job of fulfilling it. It explains crucial behaviors such as the cost per call, the data persistence side-effect (upserting), and the caching behavior governed by the 'refresh' parameter.

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 definition is direct and efficient. It front-loads the core purpose and then adds technical behavioral details in a single, cohesive statement. It avoids unnecessary fluff while being comprehensive.

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 small input schema, the description is exceptionally complete. It covers the input requirements, the expected output content, the financial cost, and the data management side-effects. No key behavioral or functional gaps remain.

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 100% schema coverage, the baseline is 3. The description adds value by providing a concrete URL format example and linking the 'refresh' parameter directly to the cost/caching mechanism, adding context beyond the schema's structure.

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 action ('Fetch') and the resource ('LinkedIn person profile'), specifying the exact data points returned (headline, role, history, education). However, it does not explicitly differentiate its scope from highly similar siblings like get_profile_summary.

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 provides a strong usage guide by detailing the operational cost (5 credits) and the persistence/side-effect behavior (upserted into people and linkedin_profiles). This context helps the agent understand the practical implications of using this specific tool.

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

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

With no annotations, the description carries the full burden and performs well: it discloses credit costs, page-based charging, the 250-post cap, caching behavior via the refresh parameter, and the persistence side effect of storing results in the post library and linking them to a linkedin_profiles row.

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

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

Three tight sentences with no waste: purpose first, cost second, storage/linking behavior third. Every sentence carries actionable information and the most important scoping detail 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 3-parameter tool with no output schema and no annotations, the description is largely complete: it covers cost, limits, caching, and the important side effect of writing to the post library. It stops short of describing the returned post shape, but the storage side effect gives enough context to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents linkedin_url, max_posts, and refresh in detail. The description reinforces the 250-post cap and per-page credit model but adds no parameter semantics beyond what the schema provides, making 3 the correct baseline.

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

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

The description names a specific verb and resource: 'Fetch recent posts from a LinkedIn person profile.' This clearly separates it from company-oriented siblings like linkedin_company_posts by specifying 'person profile,' though it does not explicitly name alternatives.

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

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

The description implies usage by tying results to the post library and profile-brief for 'research-only prospects,' but it never states when to choose this tool over linkedin_post_search, get_posts, or linkedin_profile_info. The context is helpful but not explicit 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?

With no annotations, the description carries the full behavioral burden. It discloses cost ('Costs 5 credits per call'), but this is misleadingly absolute because the schema states cached results are returned free unless refresh=true. It also omits read-only safety, caching behavior, and return characteristics, leaving important operational context to the schema.

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

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

Two short sentences with no waste. The core action is front-loaded, followed by a concise use case and cost 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 simple two-parameter read tool, the description covers the action and a use case. However, without annotations or an output schema, it should say more about what a result contains, how far back 'recent' extends, and how caching affects returned data and cost.

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

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

Schema description coverage is 100%, so both linkedin_url and refresh are already documented in the schema. The description adds no parameter-level meaning beyond what is structurally provided, which fits the baseline of 3 when the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('Fetch the recent posts a LinkedIn person has reacted to') and immediately clarifies the value ('inferring interests'). It distinguishes reactions from authored posts or comments well enough for an agent to select it over siblings like linkedin_profile_posts or linkedin_profile_comments.

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 'Useful for inferring interests' gives implied usage context, but there is no explicit when-to-use guidance, no exclusions, and no named alternatives such as linkedin_profile_posts or linkedin_post_reactions. The agent must infer the appropriate scenario.

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

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

With no annotations, the description carries the full burden. It adds genuinely useful context the schema can't express: the result includes member counts, all three collection types are returned together, and the call is free (0 credits). However, it does not state read-only semantics, ordering, or pagination behavior for what is presumably a potentially large list.

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

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

Three short sentences, front-loaded with the core action, then the scope, then the cost caveat. Nothing is repeated and every sentence adds information.

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

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

There is no output schema, so the description must convey the return shape; it does so only partially (member counts, three types) and leaves the per-collection fields, ordering, and any pagination unspecified. For a simple zero-required-param list tool this is adequate but not complete.

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

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

Schema coverage is 100% and the enum is self-documented, so the baseline is 3. The description earns an extra point by explaining what the enum values actually mean in domain terms — smart collections are 'predicate-based' and auto_stream collections are 'system-managed' — which tells the agent something about mutability that the schema does not.

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

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

States a specific verb and resource ('List all post collections') plus the returned enrichment ('with member counts'), which tells the agent exactly what it gets. It also enumerates the three collection kinds, so an agent can distinguish this from list_segments or list_streams by resource alone, though it never names those siblings explicitly.

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

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

Usage is only implied: an agent can infer this is the discovery step before add_to_collection or resolve_collection, but the description never says when to call it or when a different listing tool (list_segments, list_streams) is the right choice. No exclusions or prerequisites are stated.

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

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

With no annotations at all, the description carries the full burden; it discloses that results are scoped to the authenticated user and that the payload is profile IDs, which are meaningful behavioral facts. It omits volume/pagination behaviour, ordering, and what happens when the user has no tracked profiles.

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

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

Two short sentences with no filler, and the identity/scope statement is front-loaded before the return-value note. Every sentence carries information.

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

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

There is no output schema, so the description must describe returns, and it does at a high level ('profile IDs'). For a no-param list tool, however, an agent still cannot tell how many profiles come back, whether anything besides IDs is included, or how to page through results.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The schema is an empty object and the description correctly implies no input is required.

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

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

States a specific verb and resource ('List all tracked LinkedIn profiles') plus the scope ('for the authenticated user'), which separates it from catalog-search siblings like linkedin_people_search. It never names a sibling directly, so an agent must infer the boundary between 'tracked profiles' and searched profiles.

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?

'Returns profile IDs needed by other tools' implies a discovery-then-fetch workflow, which is useful context. But there is no explicit statement of when to call this versus linkedin_people_search, linkedin_profile_info, or get_profile_summary, and no prerequisites or 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?

With no annotations, the description carries the burden, and it does disclose two useful traits: results include member counts and the call is free (0 credits). It omits pagination behavior, result limits, and whether empty results or permissions errors are possible, so the disclosure is partial.

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

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

Three short sentences, front-loaded with the action and resource. The gloss defining audience segments is arguably extra but cheap and helps the agent confirm the resource; the cost note is placed last where it belongs.

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

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

For a one-optional-param, read-only list tool with no output schema, the description covers purpose, scope, expected return content, and cost. The main remaining gap is not distinguishing this tool from the other segment-related tools.

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

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

Schema description coverage is 100% and the single optional enum parameter (type: manual/smart/auto_stream) is fully documented in the schema. The description never mentions filtering by type, so it adds nothing beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ("List all audience segments") plus scope ("for the authenticated user") and return content ("with member counts"). It doesn't explicitly differentiate from near-siblings like list_segment_templates or resolve_segment, but the core purpose is unambiguous.

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

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

No guidance on when to use this versus list_segment_templates, resolve_segment, or list_collections, and no prerequisites stated beyond "authenticated user." Usage is only implied by the verb.

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?

No annotations are provided, so the description carries the full burden, and it does disclose the cost profile ('Free — costs 0 credits'), which is real behavioral context an agent would otherwise have to guess. It leaves unstated whether templates are system-provided/static and says nothing about result shape, but for a zero-parameter read it covers the main risk (credit cost).

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

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

Two short sentences, no filler. The core purpose is front-loaded and the downstream usage and cost note follow in a logical order.

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 parameterless list with no output schema, the description supplies purpose, follow-up usage, and cost. The only meaningful gap is the shape of each returned template (id, name, description), which an agent would need to use the ids correctly.

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

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

The tool takes zero parameters, so the baseline is 4. The description goes slightly beyond by explaining what the returned template id is for, which is useful semantics about the output even though it cannot describe input params.

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

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

States a specific verb and resource: list available smart-segment templates. The mention of template ids feeding create_segment implicitly separates it from the sibling list_segments, which returns segments themselves rather than templates, though it never names that sibling explicitly.

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

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

Gives a clear workflow: call this first, then pass a returned template id to create_segment to pre-fill the config predicate instead of authoring one manually. No explicit exclusions or when-not-to-use guidance, but the intended context is unambiguous.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the set of stream kinds returned and the migration relationship to list_profiles, which is useful, but says nothing about default filtering behavior (active-only), ordering, pagination, or result shape — all of which an agent needs to interpret the output.

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

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

Three tight sentences with the core action first, the filter hint second, and the sibling/migration note last. No filler, and the most decision-relevant 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-required-parameter read tool with full schema coverage and no output schema, the description gives enough to select and call it correctly. The remaining gap is return semantics — whether results are grouped, ordered, or truncated — which matters for a list endpoint but is a modest omission.

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

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

Schema description coverage is 100% and both parameters are documented inline, so the baseline is 3. The description repeats the `type` filter and lists values that already appear in the enum, adding no syntax, default, or interaction detail for `include_inactive` beyond what the schema states.

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

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

States a specific verb and resource ('List all research streams for the authenticated user') and then enumerates the concrete stream types returned (external profiles, companies, topics, hiring signals, ad watches, own_profile). This clearly separates it from feed-level siblings like get_stream_feed and mutation siblings like create_stream/pause_stream.

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

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

Explicitly routes the agent: use this instead of list_profiles for the streams-first model, while noting list_profiles still works for V1 callers, and points to `type` for filtering. It doesn't cover when to prefer get_stream_feed or how include_inactive should drive a decision, so it stops short of full when/when-not coverage.

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

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

No annotations exist, so the description carries the full burden. It does add real context beyond the schema — 'append' implies additive, non-destructive writes, and 'Free — costs 0 credits' is a cost signal unavailable anywhere else. However, it omits permission/auth needs, duplicate or re-log behavior for the same person and action, and what happens when the person_id or campaign_id does not exist.

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

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

Two sentences, front-loaded with the action and followed by the usage rationale. Nothing is padding; even the cost clause is a distinct fact.

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 4-parameter write with full schema coverage and no output schema, the description covers purpose, trigger events, downstream effect, and cost. The remaining gap is duplicate/error behavior, which matters for a logging tool but is a single omission rather than a systemic one.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema, giving a baseline of 3. The description restates the action values in plain prose but adds no new semantic detail such as idempotency per action or how note is stored or surfaced.

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

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

States a specific verb and resource ('Append an entry to the outreach log') scoped to a Constellation campaign. It also names the downstream consumer, get_campaign_stats, which makes the tool's role in the sibling set 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?

Explicitly says when to use it by enumerating the four recordable events (connection requests, acceptances, replies, no-responses) and the purpose (feeding rate stats). No when-not guidance or exclusion versus a hypothetical update/delete counterpart, which keeps it out of the 5 tier.

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

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

With no annotations, the description carries the full behavioral burden and does well on cost: it discloses that credit spend scales with targets, is bounded by max_targets, caps near ~175 credits, and that actual cost is returned in the response. It does not clarify whether the tool persists/writes anything (e.g., a stored queue) or is purely a read/compute operation, which is a remaining gap given the total absence of 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?

Four tightly packed sentences that are front-loaded with the purpose, then the pipeline, then the cost model. Every sentence carries information and none repeats the schema 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 three-parameter composite tool with no output schema and no annotations, the description covers purpose, internal mechanics, and cost well. The one shortfall is that with no output schema it should be a bit more explicit about the returned structure of the 'prioritized outreach queue' beyond a single phrase.

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

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

Schema coverage is 100%, so the schema already documents all three parameters, including that each target costs ~3 credits and the default keyword list. The description adds only the aggregate framing ('bounded by max_targets', '~175 credits'), which is marginal value beyond the structured fields. Baseline 3 is appropriate.

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

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

The description states a specific verb (map) and resource (professional graph around a target company) and even outlines the internal pipeline: find decision-makers, pull posts/reactions/comments to identify engagers, score connections, produce an outreach queue. This clearly distinguishes the tool's scope. However, it never names the sibling tools it bundles (score_connections, get_outreach_queue, traverse_graph), so an agent must infer the difference itself.

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

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

Usage is implied by the workflow description — reach for this when you want an end-to-end prioritized outreach queue for one account. But there is no explicit when/when-not guidance, no recommendation to use this instead of the individual scoring/queue tools, and no prerequisite or exclusion stated. The agent is left to infer the selection criteria.

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

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

With no annotations present, the description carries the full burden and does well: it discloses that the effect is scoped to scheduling rather than deletion ("Existing posts remain in the library"), that it is reversible via resume_stream, and that own_profile streams are rejected. It does not mention permission/auth requirements or what the call returns on success, which keeps it below a 5.

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

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

Three short sentences, front-loaded with the effect, then the data-retention reassurance, then the alternative and the exclusion. Nothing is redundant and nothing could be cut without losing an operational fact.

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

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

For a single-parameter state-change tool with no annotations and no output schema, the description covers effect, data safety, reversibility, and a failure precondition. Only auth requirements and confirmation of return state are absent, which is a minor gap at this complexity.

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

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

Only one parameter and schema description coverage is 100%, with the schema already telling the agent to take the ID from list_streams. The description adds no further semantics about stream_id, so the baseline 3 applies.

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

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

States a specific verb and resource ("Pause a stream") plus the precise mechanism it affects ("stops running on its cron schedule"). This cleanly separates it from delete_stream, run_stream_now, and resume_stream in the sibling 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?

Gives an explicit alternative ("Use resume_stream to re-enable it") and an explicit exclusion ("own_profile streams are billing-managed and cannot be paused here"). An agent knows both the reverse operation and the case where this call will fail.

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

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

With no annotations, the description carries the full burden. It usefully discloses that no account is needed and that the input comes from preview_profile, but it does not state read-only behavior, credit usage, rate limits, or output characteristics.

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 compact sentence that front-loads the returned insights and appends the key prerequisite and auth note. 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 simple one-parameter read tool with no output schema, the description adequately names the return values, the prerequisite, and the no-account condition. It could be slightly more complete by clarifying read-only safety, but the essentials are present.

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

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

Schema coverage is 100% and the single parameter is already documented as the preview_id returned by preview_profile. The description adds no syntax or format details beyond the schema, so baseline 3 is appropriate.

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

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

The description states the specific insights returned (best day, hour, format, length) and scopes them to a previewed profile from preview_profile. It implicitly distinguishes itself from get_posting_insights via 'previewed profile' and 'No account needed,' but does not name the sibling explicitly.

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

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

It gives a clear prerequisite ('from preview_profile') and a condition ('No account needed'), which implies when to use it. However, it does not explicitly say when to use get_posting_insights instead or state 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?

With no annotations, the description does real work: it discloses that it pulls the latest ~50 posts, that this happens once per profile, and what the response contains (preview id, post count, one-line summary). Auth context is also covered via the Flux-account and sign-in claim flow, though error or rate-limit behavior is 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 tight sentences, front-loaded with the core action and scope, followed by the return values and then the next-step tooling. Every sentence carries actionable information with no filler.

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

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

Given one parameter, no output schema, and no annotations, the description explains the key return values and the follow-on workflow sufficiently for an agent to call it correctly. It could be slightly richer about what the 'one-line posting summary' contains or how errors are surfaced, but nothing essential is missing.

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

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

There is one parameter with 100% schema description coverage, and the schema already defines linkedin_url with an example. The description implies the input is a public LinkedIn profile or company URL but adds no syntax or format detail beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb (analyze) and resource (a public LinkedIn profile or company page) and specifies the account-free scope, which helps separate it from account-based tools. It does not explicitly differentiate from siblings like linkedin_profile_info or get_profile_summary, so it falls just short of a 5.

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

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

Clearly says when to use it: public profiles/company pages without a Flux account, with the 'once per profile' limit noted. It also names the follow-on tools preview_posting_insights and claim_preview with their conditions, though it does not explicitly say when not to use it in favor of 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?

No annotations are provided, so the description carries the full burden. It usefully discloses idempotent-like behavior (missing members silently ignored) and cost (0 credits), but says nothing about permissions, whether the collection must exist, or irreversibility of the removal.

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

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

Two short sentences with no waste; the core action is front-loaded and the caveat plus cost follow immediately.

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

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

For a two-parameter, non-destructive-ish removal tool with no output schema, the description covers the main behavioral caveat and cost. Minor gaps remain on permissions and collection-existence preconditions.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema, including the 1-1000 range and the list_collections hint. The description only restates 'by post_id' and adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource with scope: 'Remove one or more posts (by post_id) from a collection.' The inverse relationship to add_to_collection is obvious, but the description never names an alternative explicitly.

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

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

Implicit usage is clear from the verb, and 'Missing members are silently ignored' hints at when calling is safe. However, no explicit when-to-use/when-not guidance or named alternatives (add_to_collection, remove_from_segment) are given.

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

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

With no annotations, the description carries the burden and delivers two non-obvious facts: missing members are silently ignored (idempotent, no error on stale ids) and the call is free at 0 credits. It omits permission requirements and whether the segment is recomputed after removal, keeping it short of a 5.

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

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

Two sentences, zero filler, action front-loaded before the caveat about ignored members and the cost note. Every clause carries information an agent can act on.

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

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

For a simple two-parameter removal with no output schema, the description covers what the tool does, the idempotency behavior, and the cost. The only real gap is the absence of any statement about what is returned or whether it is a bulk partial-success operation.

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% — segment_id and person_ids (with the 1-1000 bound) are already documented. The description only restates that removal is keyed by person_id, adding minimal meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (remove) and resource (people from an audience segment), plus the key identifier (person_id). The polarity is unmistakable against sibling add_to_segment, so an agent can route correctly without inspecting either schema.

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

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

Usage is implied by the verb and the mention of a target segment, and 'costs 0 credits' helps when weighing against paid alternatives. It never explicitly states when to prefer this over add_to_segment or remove_from_collection, or whether the segment must already exist.

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

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

With no annotations present, the description carries the full burden and mostly delivers: it discloses that the operation is cost-free, that behavior branches by collection type, and that smart collections are evaluated by predicate rather than read from storage — a meaningful, non-obvious trait. It does not state whether the result is truncated at the schema's limit (default 1000, max 5000) or what happens for a missing/unknown collection_id.

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

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

Three short sentences, front-loaded with the core action and output, then the branch conditions, then the cost note. Every sentence earns its place with no restatement of the 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 two-parameter, fully documented, non-nested read tool with no output schema, the description covers the essential contract: what is returned (post_ids) and how membership is determined. Remaining gaps (truncation at limit, ordering, error behavior for invalid ids) are minor but real.

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% — collection_id's provenance (list_collections / create_collection) and limit's bounds are already documented in the schema. The description adds no additional parameter semantics beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Resolve a post collection') plus the concrete output ('a list of post_ids'), and the second/third sentences distinguish the collection kinds (manual/auto_stream vs. smart) so the agent knows exactly what resolving means in each case. This clearly separates it from siblings like add_to_collection or get_posts.

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

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

Gives clear operating context, including which collection types it handles and the explicit cost signal ('Free — costs 0 credits'), which is a real decision input when alternatives like get_posts cost credits. It does not explicitly name an alternative tool or state when not to call it, 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?

With no annotations, the description does real work: it discloses the zero-credit cost, and that smart segments are evaluated at call time against the people table rather than read from storage — a meaningful behavioral distinction. It does not state truncation behavior when limit (max 5000) is hit, whether results are ordered, or what happens for an unknown/invalid segment_id.

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

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

Three short sentences, each earning its place: definition and return type first, per-type behavior second, cost last. Zero padding and no 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 2-parameter read tool with a 100%-covered schema and no output schema, the description covers what is returned (person_ids), how it is produced per segment type, and its cost profile. The remaining gap is pagination/truncation semantics against the 5000 max limit, which the agent would need for large segments.

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

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

Schema description coverage is 100%, so both segment_id and limit (default 1000, max 5000) are already fully documented. The description mentions the `config` predicate that segment_id ultimately resolves, but adds nothing about how limit bounds or truncates the returned list. Baseline 3 applies when the schema carries full parameter 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?

States a specific verb+resource and the exact output shape: 'Resolve an audience segment into a concrete list of person_ids.' It even breaks the purpose down by segment type (manual/auto_stream vs smart), which is unusually informative. It never names the closest sibling, resolve_collection, so sibling differentiation is implied by resource name only.

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

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

It explains the two operational modes ('returns stored members' vs 'evaluates the segment's config predicate against the people table'), which tells the agent when results are cheap/likely-instant versus computed. The 'Free — costs 0 credits' line gives a concrete reason to prefer this over credit-consuming siblings. There is no explicit when-not-to-use or named alternative, though.

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?

No annotations exist, so the description must carry the behavioral burden and it largely does: it discloses exactly which fields change (active=true, next_run_at cleared) and that execution is deferred to the next cron tick rather than immediate. It omits auth requirements, idempotency/error behavior on a non-paused stream, and the response shape.

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

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

Three short sentences, zero filler, with the core action front-loaded and the restriction last. Every sentence contributes distinct information.

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

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

For a one-parameter mutation with no output schema, the description covers what changes, when it takes effect, and a key eligibility restriction. Only the return value and failure modes are unstated, which are minor for this complexity.

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

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

The single parameter is fully documented in the schema ('Stream ID from list_streams'), so the schema carries the semantics. The description adds nothing about stream_id beyond that, which is the expected baseline given 100% 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?

States a specific verb and resource ('Resume a paused stream') and then explains the mechanism: sets active=true, clears next_run_at to queue on the next cron tick. That mechanism implicitly separates it from run_stream_now (immediate run) and pause_stream (the inverse), so an agent can distinguish it without opening other 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?

Clear precondition (the stream must be paused) and an explicit exclusion: own_profile streams are billing-managed and cannot be resumed here. It stops short of naming the alternative route for those streams, which keeps it off 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?

With no annotations, the description carries the full load and does well: fire-and-forget dispatch, asynchronous post collection, one-page-upfront credit settlement, and early-stop runs costing less. It does not cover idempotency (does running twice double-charge?), permission requirements, or rate limits — meaningful gaps for a credit-consuming mutation, but the billing transparency is unusually strong.

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

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

Front-loaded with the action, then cost model, then prerequisite, then follow-up. Five sentences, each carrying distinct information; the billing nuance is the longest but is genuinely non-obvious and worth the 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 4-param, no-annotation, no-output-schema mutation tool, it covers behavior, cost, prerequisites and where to look afterward. The remaining gap is what the dispatch response actually contains and whether repeated invocations stack, but an agent can call this correctly.

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

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

Schema description coverage is 100% and the schema already explains resume, max_pages and history_days in depth, including their interaction. The description's billing sentence reinforces max_pages but adds no new parameter-level semantics, so the baseline 3 applies.

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

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

Opens with a specific verb+resource and a distinguishing scope: 'Trigger an immediate run of an active stream, bypassing its schedule.' That separates it cleanly from pause_stream, resume_stream and create_stream without needing to name them.

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