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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description goes beyond those by disclosing batch error semantics ('per-id 4xx failures mapped to {id: {error: detail}}; any 5xx aborts the whole call'), error prefix formatting, 403 access-denied semantics for for_company, and unknown-filter 422 rejection. This is rich additional behavioral 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?

The description is extremely long and thorough, but there is redundancy and some structural noise: the ads subsection contains a stray '|' before creative, and the prose is a dense monologue. Some content (e.g., full subtype enumerations) is duplicated in the schema's subtype description. While every sentence adds value, the density approaches the edge of maintainability and readability.

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

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

This is a highly complex tool with 24 entity types, 5 parameters, nested objects, batch semantics, and per-type id/filter variants. With no output schema, the description carries the full burden of explaining return shapes, and it does so extensively—covering response maps, error mapping, polling behavior, filters per type, and access control. For a tool of this complexity, this is remarkably 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%, yet the description substantially enriches the semantics. It explains the scalar/array dimension difference for plan ('SCALAR id = the plan UUID; ARRAY id = PERSON UUIDs'), the per-type meaning of id, the exact filter keys per type, the by parameter being REQUIRED for ads.attribution, and full for_company resolution semantics. This far exceeds the baseline 3 for high coverage.

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

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

The description opens with a specific verb+resource: 'Fetch one entity (or a small batch) by type + id — the consolidated read tool.' It clearly defines what it does and frames itself as the consolidated read tool, distinguishing it from sibling read tools like get_person_360, get_deal_360, and search. The extensive type breakdown makes the scope unmistakable.

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

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

The description provides explicit when-to-use guidance via the type semantics, cross-referencing sibling tools: 'create/update/diagnose/member changes with manage_campaign', 'for the enriched view use get_deal_360', 'poll after async tools like people create / import_prospects'. It also gives explicit guidance on batch limits, id semantics, and which types take no id. This is exemplary alternative-tool differentiation.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavioral context: team scope surfaces owner-named ties but keeps evidence private, teammate results carry no actions, and the tool performs no write/LLM/send. This aligns with and enriches the annotations without contradicting them.

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

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

The prose is concise and front-loaded with purpose and safety guarantees. However, the massive embedded example response takes substantial space and largely duplicates the output structure the schema already implies. The example is genuine illustrative content but could be trimmed; despite this, the written description itself is efficient.

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 complex tool with a rich response schema and detailed field-level schema descriptions, the description provides adequate context: it covers safety traits, scope semantics, team-mode privacy behaviors, and references for_company via get_operator_overview. The diagnostics/exclusions/next_actions fields in the response are self-explanatory from the response example, so coverage is reasonably 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 75%, with scope, target, and for_company each having detailed descriptions in the schema itself. The description adds value around the scope semantics (team behaviors) but doesn't add much beyond what the schema's for_company description already provides (which is notably rich). The limit parameter has a default and max of 3 with no additional description needed.

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

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

The description clearly states the tool reads relationship truth for one target and explicitly lists what it does NOT do (no write, LLM call, or send). It distinguishes somewhat from siblings by emphasizing its read-only relationship-finding nature, though siblings like get_person_360 could overlap in purpose and no explicit differentiation is given.

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 the scope='team' behavior clearly and the response example implies what results look like. However, it doesn't explicitly state when to prefer this tool over get_person_360 or search, nor does it provide exclusions. The threshold/use cases (e.g., 'when you need a warm introduction path') are implied but not 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?

The description goes well beyond the readOnlyHint=true annotation. It discloses critical behavioral traits: that every campaign asked for is returned (including unavailable ones as availability='unavailable'), that outcome_cutoff discounts recently-started campaigns, that coverage_complete:false means the numbers should not be ranked, and that data_watermark limits ingestion recency. It also documents server-enforced window rules. This is rich, value-adding behavioral disclosure.

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 somewhat long but well-organized with clear section headers ('Reading the response', 'Window rules'). Every section adds distinct value, though the response-parsing section could arguably live in an output schema. The structure with bolded field names and explicit 'do not rank' guidance earns its length despite being longer than ideal.

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 complex tool with 5 parameters (3 date-time fields with subtle interactions), no output schema, and nuanced availability/coverage semantics, the description is remarkably complete. It explains the window rules, the reading of each response field, the behavioral guarantees, and the alternative tool. Given the complexity, this is close to fully self-sufficient for an agent to use 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 baseline is 3. However, the description adds meaningful semantic value by explaining the intent behind outcome_cutoff ('as of' moment, keep identical across compared campaigns), clarifying that end_at bounds touches not outcomes (which is non-obvious), and explaining the availability='unavailable' behavior for campaign_ids. This enriches the schema definitions meaningfully.

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

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

The description clearly states the tool's purpose: compare campaigns on real outcomes (contacted, replied, meetings booked) and answer 'which of these campaigns actually worked' for up to 100 campaigns over a UTC window. This is a specific verb+resource combination that distinguishes it from sibling tools like get_performance_metrics, directly addressing what it does differently.

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 states when to use this tool vs the alternative: 'Use get_performance_metrics instead for funnel and time-series views of the whole account; this tool is for ranking specific campaigns against each other on a like-for-like cohort.' This names the exact sibling tool and the distinguishing use case, providing both when-to-use and when-not-to-use guidance.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description adds rich behavioral context beyond these: attachments carry type/filename/url and must be opened to review actual files, assets are public-at-upload in a public bucket, error_message surfaces publish failures with reverted posts showing up. It even discloses that a document publishes as a swipeable carousel. This is genuinely valuable safety-relevant behavior disclosure.

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?

Well-structured with headers, example response, and logical flow from purpose to enrichment details to usage guidance. The VRU-726 attachment details and for_company semantics are substantive but somewhat verbose; a couple of sentences could be tightened without losing value. Front-loaded with the core purpose before diving into specifics.

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 7 parameters, 100% schema coverage, and no output schema, the description does substantial work: it clarifies return shape (items, total_pending, offset, limit via example), attachment semantics, error handling, and pagination. The example response only shows partial fields, leaving some interpretation, but overall the description is quite complete for a complex tool with 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 coverage is 100%, so the baseline is 3. The description adds meaningful value beyond schema: post_ids is detailed as the deterministic 'review the post I just drafted' path that bypasses the status filter and is capped at limit ids. for_company gets deep semantics (exact match, 400 on ambiguity, 403 meaning, operator role not auto-granted). The description compensates well above baseline for parameter behavior the schema merely labels.

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

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

The description clearly states the tool reviews content post drafts with performance context and calendar awareness, and enumerates exactly what's enriched (performance stats, calendar neighbors, tone instructions, calendar summary). Purpose is specific and differentiated from siblings like get_outreach_review and manage_content. Slightly loses a point because the first sentence 'Review content post drafts' is somewhat generic without the grounding given by 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?

Explicitly instructs to use `post_ids` for deterministic lookup of a freshly drafted post, and to use this before scheduling/publishing. The for_company parameter includes guidance on listing companies via get_operator_overview. However, it doesn't explicitly distinguish from manage_content (drafting vs reviewing) or state when NOT to use it, leaving some room for ambiguity.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, which already cover the safety profile. The description adds substantial behavioral context beyond this: weekly Monday-anchored windows, people-not-meetings counting, NOT date-filtered caveats, sections_degraded semantics (returned as 0/[] means UNKNOWN), and recommendation priority ordering. It also instructs agents to report channel_holds before claiming all-clear. This is rich, non-redundant behavior disclosure.

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 extremely thorough and front-loaded with the purpose sentence, and well-organized with clear sections (SUGGESTED ACTIONS, TIME WINDOWS, Returns, units). However, it is very long — defining each return field in detail — and much of that could arguably live in the output schema. Not every sentence earns its place given the verbosity, though the structure is excellent.

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?

Despite no output schema, the description fully documents every returned field with units, scoping, and edge cases, plus the top_recommendation enum and priority order. The detailed example response also fleshes out the return shape. For a complex aggregation tool with a single optional parameter and rich output, this is complete down to TTL and VRU ticket references.

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% for the single optional parameter, so the schema already documents for_company. The description adds meaningful extra semantics: clarifies partial/substring matches fail, ambiguous names raise 400, lists the company-listing tool (get_operator_overview), and details how access is enforced via company_users membership. This significantly enriches the bare schema text, justifying above-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 clearly states this tool returns a daily briefing aggregating many operational metrics: pending approvals, replies, meetings, pipeline, stalled deals, plans, discovery jobs, and a recommendation. It explicitly declares its 'everything you need to start your day' scope. Among (27) siblings like get_engagement_review, get_performance_metrics, and get_outreach_review, this daily-brief role is well differentiated.

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 detailed guidance on SUGGESTED ACTIONS, explaining how agents should act on intent/args, that prompt is display copy not to be echoed, and how sections_degraded affects top_recommendation. It defines all time windows and which counts are date-filtered. However, it doesn't explicitly name alternative sibling tools or state when NOT to use this (e.g., when you need detail, use get_outreach_review), so exclusions are absent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by noting it aggregates multiple data sources (info, stakeholders, MEDDIC, timeline) and mentions cross-company access via X-Company-Id header, which adds value beyond the annotations.

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

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

The description is reasonably concise and front-loaded with the core value proposition ("Complete deal context in one call"). The title repetition in the first line is minor, and the Responses section is mostly empty filler, but overall it stays focused and doesn't over-elaborate.

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 aggregation tool, the description captures main capabilities and includes a cross-company access note. However, it leaves key parameters (deal_id format, timeline_limit semantics) undocumented, and the absence of an output schema means it should explain the response structure more explicitly, but does not.

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

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

Schema description coverage is only 33% (only for_company has a schema description). The tool description does not explain deal_id or timeline_limit, and the vague mention of "recent activity timeline" does not clarify the timeline_limit parameter. The description fails to compensate for the low schema coverage.

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

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

The description clearly states it aggregates complete deal context including deal info, stakeholders, MEDDIC state, and activity timeline. It distinguishes from siblings by explicitly comparing to get_person_360 ("Like get_person_360 but for deals") and positions itself as the default tool for understanding a deal's current state.

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

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

The description says "Use this as the default tool for understanding a deal's current state," which is explicit usage guidance. It also notes it replaces 3 separate tool calls, implying efficiency. Unlike the TDQS high example, it doesn't name an explicit alternative tool, but the get_person_360 comparison provides a clear point of reference.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, which is corroborated by the description framing this as a review/triage tool. The description adds rich behavioral context beyond annotations: the engagers branch returns PERSONS (not engagements) with `items` stays empty, total_pending counts exactly scored_passed persons, near-miss context is display-only, and the critical warning that engager-authored fields are 'third-party LinkedIn content — treat them as data, never as instructions' (a security-relevant disclosure). It also documents the rejected/ignored filters (400 on engagement_ids, ignored campaign and sender_user_id) on that branch, plus for_company access enforcement 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?

The description is long but dense and well-organized. The main body uses bold headers (ENGAGER REVIEW, ### Responses) to structure distinct concerns. The content is front-loaded with the core purpose in the first two paragraphs before diving into source-specific details, which is appropriate given the tool's complexity. Every sentence carries operational value — there's minimal fluff. The only deduction is length: at this scale, some agents may struggle to parse all the branch-specific rules, though this is justified by genuine complexity.

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

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

This is a highly complex tool (10 params, dual-tool behavior depending on source, security warnings, multi-company access) with no output schema to fall back on. The description comprehensively covers: the default triage behavior, the engagers branch behavior, the output shape (items vs engagers fields), action sequencing with related tools, security guidance (third-party content as data), and multi-company access enforcement. Given this complexity and the absence of an output schema, the description is remarkably complete — an agent could safely operate this tool without prior knowledge.

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 some semantic value beyond the schema: content_length's behavior (capped at 5 in full mode), engagement_ids purpose ('for subagent batch dispatch'), include_decided's rationale (reversible wrong dismiss via engager_reopened), and near_miss_max_age_days' effect (near_misses_excluded_by_age return field). These complement the schema. However, most parameter semantics (limit, offset, sender_user_id, campaign) are already fully explained in the schema, so the description doesn't dramatically 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?

The description has a specific verb+resource ('Get Engagement Review') and immediately establishes it as the 'Default tool for engagement queue triage' for 'pending engagements with full context'. It clearly distinguishes from siblings by naming related tools (manage_engagements, manage_messages, manage_campaign) it complements, and explicitly details the engagers branch that differentiates it from other review tools like get_outreach_review or get_content_review.

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

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

The description provides extensive guidance: 'Start here when reviewing warming comments, nurture reactions, or marketing engagements', explicit content_length selection advice ('full' for detailed, 'preview' for quick scanning), and detailed ENGAGER REVIEW branch instructions with a clear directive to 'CHECK in_motion BEFORE acting'. It also explicitly warns what NOT to do (acting on in_motion persons risks double outreach) and prescribes the action sequence (act with existing tools FIRST, then record with acted_via).

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the priority sorting semantics and category breakdown, which is useful context beyond the annotations. However, it doesn't disclose pagination behavior, whether results are deterministic, or what happens with empty action lists. The for_company param description does add substantial behavioral detail about error semantics (400 for ambiguous names, 403 for access denied), which is helpful.

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 well-structured with a clear priority breakdown and a compact example response. The bulk of the content is appropriately placed in the parameter schema rather than the description. It's slightly longer than minimal but every sentence adds value — the priority tiers and example response are genuinely useful. Could be trimmed of the redundant title line but overall efficient.

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 filtered list tool with two well-documented parameters (100% schema coverage) and readOnly/destructive annotations, the description provides good context: it explains the sort order, the categories included, and gives an example response shape. The example response compensates for the lack of an output schema. Minor gaps: no mention of whether limit is applied after sorting (presumably yes) or behavior with zero actions, but these are low-stakes for a read-only aggregation tool.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (limit with min/max/default, for_company with detailed semantics). The description adds the priority/sorting context but doesn't add parameter-level meaning beyond what the schema provides. The for_company parameter description is exceptionally detailed about matching semantics and error behavior, but that's in the schema, not the description. Baseline 3 is appropriate since schema carries the 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?

Clear verb+resource: 'get' a prioritized 'next-action list' for the user. The description specifies the exact sorting priority tiers (P1 replies, P2 approvals, P3 follow-ups/deals/tasks, P4 prospects), distinguishing this from sibling tools like get_daily_briefing or get_deal_360 which have different scopes.

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 implicitly defines when to use it (when you need the user's prioritized action queue) by listing the exact categories and priority tiers. However, it doesn't explicitly contrast with siblings like get_engagement_review or get_outreach_review, so the when-not-to-use guidance is implied rather than explicit. The for_company parameter description does provide clear guidance on when that param is needed ('Only needed if you manage multiple companies').

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

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

Despite strong annotations (readOnlyHint=true, destructiveHint=false), the description adds substantial behavioral context beyond them: the full-content 5-item cap to prevent connection drops, the channel_holds_degraded semantics (empty list is unknown, not healthy), the 14-day expiry window and nightly sweep auto-rejection behavior, and the crucial distinction between expired touches showing as 'rejected' with blank content (GC, not operator rejection) versus genuine rejections. It also warns that approved-but-scheduled sends must not be touched — canonical behavioral disclosure.

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?

Well-structured with clear sections (channel_holds, filtering, returns, responses) and excellent front-loading — the first lines immediately establish 'default tool for outreach queue triage'. The return-format section is detailed but organized as a bulleted spec with units labeled. It is long, but the density of genuinely useful operational guidance (prioritization, expiry windows, scheduling semantics) justifies the length. Minor deductions for some redundancy (content_length behavior appears in both the description and parameter schema, and the return field list is exhaustive).

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 complex triage tool with 6 parameters, a large multi-field return payload, and no output schema, the description is remarkably complete. It documents every meaningful field in the return shape with units, explains special states (expired, externally-scheduled, approved-pending-send), defines the scope filter semantics, and provides a full example response. The only thing not covered is a step-by-step workflow walkthrough, but the prioritization and expiration guidance compensates. Nothing material is left to guesswork.

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

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

The schema already covers all 6 parameters with descriptions (100% coverage), so the baseline is 3. The description adds real value: it explains the interactive effects between content_length and limit (auto-cap at 5), how message_ids bypasses sorting/pagination, the for_company access model (403 meaning, exact-match requirement, membership via company_users), and semantic details like the offset/limit echo behavior. It stops short of giving format examples for every parameter but meaningfully enriches the schema.

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

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

The description opens with a clear verb+resource statement ('Default tool for outreach queue triage — pending messages with full context for review') and explicitly distinguishes it from manage_messages ('write via manage_messages edit') and other sibling tools. It names the exact statuses handled ('needs_draft', 'draft'), the enriched context provided, and even frames it as 'Starting here' for the workflow, making its role unambiguous against its many 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?

Extremely thorough when-to-use guidance: it identifies this as the default triage entry point, tells agents to author via manage_messages and approve/reject via manage_outreach (naming the alternatives), explains the content_length full-vs-preview tradeoff with pagination, gives a concrete campaign filter example ('DFW CFOs'), and describes subagent dispatch patterns with message_ids. It even teaches prioritization rules (warm connected items first) and exactly when NOT to act (approved_pending_send_count must not be re-drafted).

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

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

Despite the readOnlyHint=true annotation already covering the read-only safety profile, the description goes far beyond annotations to document crucial behavioral nuances: end_date is IGNORED by reply_rates_by_channel in direct mode; contacted/funnel.meetings are unique_people not message counts; stage_funnel acceptance_rate has a 'plans vs messages' unit cross-walk warning; accepted_count is all-time in direct mode. This is exceptionally transparent about edge cases and limitations.

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 organized with clear section headers (UNIT CONVENTIONS, DATE-FILTER COLUMN PER METRIC, Returns) and useful ASCII separators. Although it is long, every section carries distinct technical information that prevents misinterpretation. Minor redundancy exists between the metric list in the intro, the Returns block, and the parameter descriptions, but this serves as reinforcement rather than 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?

For a complex tool with 6 parameters, multiple views, and rich return semantics, the description thoroughly covers all dimensions: return field units, scope, date filters, cross-walk caveats, and channel-specific behaviors. Even without an output schema, the Returns block fully documents each field's meaning. The funnel/stage_funnel/reply_rates_by_channel nuances are all explained, making this unusually 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%, so the baseline is 3. The description substantially compensates by adding cross-references to the input schema's end_date caveat ('see the end_date query-param description for details') and enumerating the date-filter column per metric. It clarifies unit semantics (unique_people vs messages) and scope for each metric that the schema alone does not fully convey.

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

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

The description clearly states the tool retrieves outreach performance metrics with two distinct views (timeseries and funnel), and provides concrete examples of when each view is appropriate. It distinguishes adequately from sibling tools like get_engagement_review, get_campaign_outcomes, and get_outreach_review by focusing specifically on time-series trends and conversion funnel analytics.

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

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

The description provides explicit when-to-use guidance: 'For T1s sent over time: view=timeseries, metric=contacts' and 'For reply rate and funnel: view=funnel.' It also specifies the for_company operator for multi-client management and references get_operator_overview as the companion tool to list companies. This clearly directs the agent on when the tool applies versus alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the aggregation behavior and response structure context. The for_company parameter description supplements the schema with detailed behavioral guidance about access enforcement, 403 semantics, and matching limitations — which is substantial added value beyond annotations. However, the core description doesn't disclose the full breadth of what's returned beyond a category 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?

The main description is reasonably concise, but the example response JSON is quite sparse and generic (empty objects, placeholder text like 'Person Id', 'Activity Type') which adds little value and consumes space. The for_company parameter description is verbose but densely informative. Overall acceptable but the response example could be trimmed or made more illustrative.

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

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

For a tool with no output schema and no annotations beyond read-only/destructive hints, the description does reasonably well listing the aggregated domains (person info, match analysis, research, activity, outreach, deal). The for_company parameter is thoroughly documented. However, there's no output schema, so the agent must infer response structure from a generic example, and the description doesn't clarify the scope/completeness guarantees of each aggregated section.

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 for_company parameter has an exceptionally detailed description covering matching semantics (EXACT match, no substring), error behavior (400 for ambiguous, 403 for no access), resolution logic, and how to discover valid values via get_operator_overview. This far exceeds the 50% schema coverage baseline. person_id, however, has no description beyond its name/title, relying on the tool name for 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 description clearly states this aggregates person info, match analysis, research, activity timeline, outreach plan state, and deal info — replacing 5 separate tool calls. This provides a specific verb ('Get'/'Aggregates') with a clear resource ('Person 360' complete context). It distinguishes itself from the 5 separate tools it replaces, though it doesn't name each sibling explicitly.

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

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

The description explicitly says it replaces 5 separate tool calls and provides complete person context in one call, giving clear guidance on when to use this tool (when you need comprehensive person context). However, it doesn't explicitly state when NOT to use it or name alternative tools like research, get_engagement_review, or get_outreach_review for focused queries.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so the read-only nature is already covered. The description adds the 'Read Stripe-backed' provenance detail and the evidence/immutable ingestion context, which is useful. However, it doesn't disclose operational traits like rate limits, pagination behavior across views, or freshness guarantees. For a read tool with good annotations this is adequate but not rich.

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

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

Well-structured with a bolded lead-in line, a bulleted list of views, and a tidy responses section. The for_company parameter description is quite verbose but that depth is genuinely valuable. Some redundancy exists (title repeated at start of description 'Get Revenue'), and the responses section only documents status-200 which is minimal, but overall the structure is clean and skimmable.

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

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

The tool has 7 parameters with view-dependent behavior, no output schema, and sparse description coverage of parameters. The description explains what each view returns conceptually but doesn't document view-parameter compatibility (e.g., does `metric` apply to metrics view only? does `binding_status` apply to bindings view only?), default behaviors, or pagination semantics. For a multi-view tool of moderate complexity, this is functional but leaves meaningful gaps in how the parameters compose with views.

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

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

Schema description coverage is only 29%, so the description carries significant burden for parameter explanation. The for_company parameter gets extensive treatment (company resolution, exact-match requirement, 403 semantics, operator-role explanation). The cursor field is documented in schema as 'opaque pagination cursor'. However, the `view`, `metric`, `currency`, `limit`, and `binding_status` parameters receive little to no semantic explanation in the description beyond what the schema enum provides — their interplay (e.g., which views accept `metric` or `binding_status`) is undocumented.

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?

Title states 'Get Revenue' clearly, and description expands with 'Read Stripe-backed revenue truth' plus enumerates four view types (connection, metrics, evidence, bindings). This clearly distinguishes it from siblings like manage_revenue (mutation) and get_performance_metrics (a different domain). The verb+resource+scope is specific, though it doesn't differentiate it from every sibling.

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

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

The description lists four views with a one-line explanation of each, giving agents clear guidance on what each view provides. The for_company parameter description is extremely detailed about when to use it and what errors occur. However, there's no explicit statement about when NOT to use this vs. alternatives like get_performance_metrics or manage_revenue, and the view-vs-metric relationship isn't clarified (which view to pair with which metric).

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

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

Annotations declare readOnlyHint=false and destructiveHint=false (imports write data but aren't destructive), openWorldHint=true. The description adds substantial behavioral detail beyond annotations: it documents that csv_start returns a job id requiring polling via fetch, explains per-action validation behavior (bad field returns precise 422), and describes the profiles_json accepted format. It also mentions the 403 company access enforcement in the for_company parameter description. This is good behavioral disclosure for a multi-action 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?

The description is densely structured with clear action groupings (Sales Navigator, CSV), which aids navigation. However, it's quite long and includes some repetition between the description and schema (e.g., payload validation 422 behavior appears in both the description and the payload parameter description). The for_company explanation is thorough but verbose. Decent structure but could be tightened.

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

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

This is a complex multi-action tool (5 Sales Nav actions + 2 CSV actions + 5 params with nested objects), yet the description covers each action's payload fields, response behavior (job id polling, 422 errors), and cross-tool integration (fetch for polling). No output schema exists, but the description explains the job-id/polling pattern. The 100% schema coverage plus per-action field documentation makes this reasonably complete for an agent to use 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% with descriptions for id, items, action, payload, and for_company. The for_company description is particularly rich, covering exact-name matching, ambiguous-name 400 errors, server-side enforcement, and the 403 semantics. The description adds concrete field-level detail for each action's payload (e.g., sales_nav_search requires {keywords, mode?...}, csv_start requires file_content + column_mapping). This meaningfully extends beyond the generic schema descriptions.

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

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

The description states it's an 'Import Prospects' tool acting as 'the consolidated import tool' for importing prospects via Sales Navigator and CSV actions. The verb+resource is clear, though 'consolidated import tool' is somewhat broad. It differs from sibling tools like manage_outreach or manage_person by focusing specifically on import/source operations for prospects.

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

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

The description details each action's fields and use cases (e.g., 'use basic for exact-name/profile resolution fallback when Sales Nav is unavailable'), providing useful context. However, it doesn't explicitly state when to choose this tool over alternatives like manage_person or managing outreach, or give exclusions/when-not-to-use guidance. The when-to-use context is clear per-action but the tool-level selection guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. Beyond that, the description adds genuinely useful behavioral detail: exact risk-heuristic formulas, the fixed '5 most at-risk' return count, and pipeline health outputs. This adds real value over the annotations alone by disclosing the scoring logic and output scope.

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 well-structured with a punchy lead sentence, a compact bulleted risk-heuristics list, and minimal output summary. The use of punctuation-dense heuristic notation (14d=+35, 7d=+20) is efficient. Minor waste: repeating the tool name as a header line and the raw 'Responses/200' block that adds little to an agent's understanding, keeping it from a 5.

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

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

For a read-only with no output schema, the description covers the return contents (risk scores, factors, health status, deal/value totals) and the risk model comprehensively. The heuristic list fully specifies scoring logic, which is unusually complete. Missing: no phrasing about default behavior when for_company is omitted (presumably the caller's own company), and pagination is not mentioned though only 5 deals are returned.

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

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

Schema coverage is 100% and the single optional parameter for_company has an extremely detailed schema description covering matching rules, error behavior (400/403 distinctions), access enforcement, and how to list available companies. The tool description reinforces this with the X-Company-Id header note. The one param is fully documented with zero gap.

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

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

The description clearly states it provides a 'Risk-first pipeline view' returning the 5 most at-risk deals with risk scores, factors, and pipeline health. The verb 'inspect' + resource 'pipeline' is specific, and the risk-focused angle distinguishes it from sibling tools like get_performance_metrics, get_revenue, and get_deal_360 which cover different pipeline aspects.

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 conveys its purpose clearly (risk inspection) and mentions the X-Company-Id header for cross-company inspection. However, it doesn't explicitly state when to use it vs. sibling tools (e.g., get_deal_360 for single-deal deep dives, get_revenue for financial metrics). The risk-heuristic detail implies a specific use case but no explicit exclusions or alternatives are named.

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

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

The description goes well beyond the annotations (destructiveHint=true, readOnlyHint=false): it explains which specific action is destructive (delete_impact), states that bulk failures are reported per-item 'never silent,' notes payload validation is delegated to the underlying route's schema, and describes the 200 Success Response. It does not fully disclose what happens to dependent/history data on delete_impact or whether state changes are reversible, but it covers the key destructive and failure behaviors meaningfully beyond the annotation flags.

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 well-organized with clear section headers (Actions, Bulk, Responses) and bulleted action definitions that are economical. It front-loads the core purpose before diving into specifics. It is moderately long but every section earns its place given the tool's three-action complexity — though the trailing 'Response' boilerplate could arguably be trimmed.

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

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

For a complex multi-action tool with 5 parameters, embedded objects, no output schema, and destructive behavior, the description does substantial work: it enumerates the action vocabulary, per-action id/payload semantics, bulk loop behavior including partial-failure reporting, payload validation expectations, and the for_company scoping rules. The description compensates well for the absent output schema and the tool's complexity, though it could detail return-value shape or side effects of state changes more explicitly.

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 value by explaining the id entity per action and the payload structure for each action type, and clarifying that `for_company` is optional and needed only for multi-company management. However, the schema descriptions are already quite rich (containing the per-action semantics and company match rules), so the description is complementary rather than adding substantial new information beyond the schema.

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

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

The description clearly states manage_account is 'the consolidated account writer' maintaining 'account state and impact history,' and enumerates three distinct actions (state, record_impact, delete_impact) with precise semantics for each. It distinguishes id-interpretation differences between actions (account company_id vs impact event id), clearly differentiating itself from siblings like manage_deal, manage_person, and manage_revenue.

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

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

The description provides clear per-action usage (id/payload meaning for each of the three actions) and explicitly flags delete_impact as DESTRUCTIVE. It covers bulk-loop behavior and max 100 items. However, it does not explicitly state when to prefer this over sibling writer tools like manage_deal or manage_revenue, nor when NOT to use it — sibling differentiation within the manage_* family is implicit rather than explicit.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description builds on this extensively. It explicitly flags 'delete: permanently delete a campaign. DESTRUCTIVE.' and 'pause: ... stops every active plan under it in one call — no per-plan pause loop. Returns {plans_paused}.' It discloses async behaviors (media_url video stores are ASYNC — poll fetch until upload_status leaves 'uploading'), idempotent store_creative behavior, 24h sweeping of unfinalized rows, server-side enforcement before spend, and the fact that payloads are validated by underlying route schemas (bad fields 422 with precise errors).

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?

Extensive but well-organized with clear section headers (Outreach actions, Ad actions, Identity setup, Bulk, Responses), plus tables for the vehicle/objective legality matrix. The content is dense and long, but every section earns its space given the tool's enormous scope — a single consolidation of campaign operations spanning outreach, ads, boost, creative storage, and identity setup. It's front-loaded with the core purpose and read paths before diving into per-action detail. Slight deduction for length making it heavy to parse at a glance.

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 6 parameters, nested objects, no output schema, and heavy complexity, the description is exceptionally complete. It covers the full action vocabulary across two campaign families, per-action payload semantics, id semantics, bulk behavior (per-item status, partial failure never silent, max 100), server-side validation behavior (400/422 codes), availability/partner gating (matched_audience_partner_gated), legal vehicle/objective combinations, async store behavior with polling guidance, identity setup requirements (set_page before page_sponsored, authorize_author before thought_leader), and error fix guidance (the error's `fix` shows the facets form). The only gap is that with no output schema, some return shapes beyond {plans_paused}/{plans_resumed} are not enumerated for all actions, but the description covers the key ones.

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 pushes higher by enriching semantics beyond the schema. It explains the id semantics per action (outreach id = campaign UUID, ad id = ad-campaign UUID, no id for boost/store_creative since no campaign exists yet), the kind parameter's full action list, payload shape for each action (e.g., {action: assign|unassign, person_ids} for members, {daily_budget_cents} for edit_budget, {content_post_id XOR creative_id} for boost), and the `items` bulk semantics. However, the description doesn't enumerate every single field of every payload in a structured way, deferring to the schema for raw shape.

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

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

The description clearly states this is 'Manage Campaign' — the consolidated campaign writer that creates and manages campaigns, with explicit action vocabulary (create, clone, update, delete, members, diagnose, pause, resume) and separate ad actions. It distinguishes from siblings by positioning itself as the writer for every campaign mutation and diagnosis, referencing fetch/search for reads. The deep specificity about the boost audience format, vehicle/objective legality matrix, and creative storage fundamentally sets it apart from a generic description.

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 explicit when-to-use guidance: 'Use this writer for every campaign mutation and diagnosis,' and directs reads to `search` with type='campaigns' and `fetch` with type='campaign'. It gives exhaustive context on tool-vs-alternative usage (resolve targeting entities via fetch before boost, the resolve-then-boost happy path), and documents constraints like partner-gated criteria rejection with the fix pointing to the facets form. The vehicle/objective matrix enumerates exactly which combos are legal vs 400-rejected.

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

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

Annotations declare destructiveHint=false, but the description adds substantial behavioral detail: publish-time creative_id 'is rejected with the pointer to edit-attach,' deleted posts are drafts-only, batch operations report per-item partial failures 'never silent,' attachment failures revert to draft with structured 422, ambiguous provider timeouts remain terminal `failed` with a warning against blind retry double-posting. It also discloses prose-gate blocking, UTM stamping behavior, and identity requirements. These go well beyond what the three boolean annotations convey.

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

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

The description is clearly structured with section headers, but it is very long and dense — covering seven actions, attachments, identities, external links, bulk semantics, and prose gate details. While every sentence carries content, the length risks cognitive overload for an agent deciding quickly. Some operational minutiae (VRU ticket numbers, exact curl invocations) could arguably be trimmed, though they serve troubleshooting value.

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

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

Given the tool's high complexity (7 actions, 5 params, nested objects, no output schema, three boolean annotations), the description is remarkably complete. It covers the full golden path, failure modes with codes, edge cases (ambiguous company names 403, public-at-upload assets), and cross-references to sibling tools for pre/post checks. The only addition would be explicit response-shape detail, but the 200/error_code structure is described, which suffices for a no-output-schema tool.

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

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

Though schema coverage is 100%, the description adds deep semantics the schema lacks: per-action payload shapes (draft payload fields, edit's empty-string-clears versus absent-leaves-untouched external_link, explicit-null-detaches attachment), id entities per action, items exclusivity, and override_reason hierarchy (honored only for owner/operator roles). The nuance around detach-versus-leave in edit is something the generic object payload schema could never express.

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

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

The description clearly states the tool drafts, schedules, and publishes LinkedIn content, labeling it 'the consolidated content writer.' It enumerates each action (draft, edit, schedule, publish, delete, draft_post) with specific verb+resource semantics and differentiates it from siblings like manage_campaign and manage_messages. The scope is unambiguous and comprehensive.

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 explicit when-to-use guidance for every action (e.g., draft_post 'never generates prose,' delete 'drafts only — published posts are not deletable here'). It references sibling tools directly (manage_campaign store_creative/set_page, get_content_review, check_prose) and provides a numbered golden-path workflow for attachments. Alternative choices and constraints are spelled out throughout.

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

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

Annotations already provide readOnlyHint=false, openWorldHint=false, destructiveHint=false, so the safety profile is declared. The description adds meaningful behavior disclosure: partial failure is reported per-item and never silent (max 100 bulk), a bad field returns the route's precise 422, and payloads are validated by underlying route schemas. However, it doesn't disclose the response/return format, error behaviors beyond 422, or state-change side effects of destructive actions like archive_pipeline.

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 densely structured with action groupings and payload specs, which is efficient for the complexity level. However, it's quite long and front-loads the overwhelming action vocabulary before the user needs it, and the Responses section is cut off mid-sentence ('Content-Type: application/json'). The per-action payload inline specs are valuable but make the description somewhat unwieldy.

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

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

This is an exceptionally complex tool (20+ actions, varied id/payload semantics, bulk processing, multi-entity targets), and the description covers action vocabulary, id requirements, payload fields, bulk semantics, and validation behavior. There's no output schema, so the return-value behavior should be disclosed but only partially is (per-item status/422). The description is strong given the complexity but could clarify return formats for the outcome-recording actions.

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 substantial meaning beyond the schema: it defines the exact payload fields per action (deal_name, person_id, company_id, deal_source with enum values and default, etc.), clarifies that id semantics change per action (deal UUID vs pipeline UUID vs stage UUID), and explains the items vs id vs payload mutual exclusivity. This richly supplements the schema descriptions for a high-complexity tool.

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

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

The description clearly states this is the consolidated deal writer for creating and managing deals through the pipeline. It enumerates 20+ distinct actions with specific intent. It doesn't explicitly distinguish from sibling manage_* tools (like manage_account or manage_revenue), but the scoped action vocabulary makes its deal/pipeline focus clear.

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

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

The description provides extensive per-action guidance: which actions take an id, which take no id, which require payload fields, which are mutually exclusive (id vs payload vs items), and which require pairs (pipeline_id+stage_id). It names alternatives by pointing to specific structured routes and even cross-references get_operator_overview for available companies. This is unusually thorough for when-to-use-what guidance.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, but the description goes well beyond by disclosing key behavioral traits: bulk id arrays (max 100) route natively, prose gate re-lints and can return error_code='prose_gate_blocked' with structured failures[].fix, override_reason is honored only for owner/operator roles (otherwise ignored and gate blocks normally), engager_dismissed is durable/irreversible via normal flow, actioned persons cannot be reopened, and unattributed warning when acted_via is absent. That's rich behavioral disclosure. Minor gap: no mention of what the 200 response body contains.

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 dense and information-rich, with good use of bold section headers and bullet-style per-action breakdowns. However, it is quite long and packs a great deal of edge-case detail (VRU-721 ticket reference, prose gate override semantics, sub-70 near-miss minting) that could be trimmed or relegated. Every sentence does earn its place for correctness, but a reader must parse substantial complexity before reaching the response spec. Front-loading is reasonable via the terse action list at top.

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

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

This is a high-complexity tool with 5 actions, two distinct id encodings, nested payload objects, and no output schema. The description is comprehensive: covers each action's id/payload semantics, bulk behavior, validation, error pathways (prose_gate_blocked, 403 company, 420 route errors), role-based authorization nuance, durability semantics of dismiss/reopen, and safety checks (in_motion flag, third-party data warning). Given the absence of an output schema and the feature richness, the description is remarkably complete.

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

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

Schema coverage is 100% and there are 5 params including nested objects. The description adds substantial semantic meaning beyond the schema: it explains which entity the id names per action (engagement UUID vs PERSON UUID for engager_*), the exact payload shapes per action ({content, content_mode?, reaction_type?} for edit; {post_text, post_id, author_name?, person_id?, tone?} for draft_comment; {acted_via?: {campaign_id|message_id}, note?} for engager_actioned), and documents the items array being for create-like actions. It generously supplements the schema, though some payload keys left open-ended ('…').

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

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

The description clearly states this tool 'Triage[s] the LinkedIn engagement queue — the consolidated engagement writer' and enumerates five distinct actions (approve, edit, skip, draft_comment, engager_*). Each action names a specific verb+resource combination. It also distinguishes the engager_* actions as a separate decision category with a different id type, which differentiates it meaningfully from siblings like manage_messages and manage_campaign.

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 extensive when-to-use guidance: explicitly tells when engager_actioned is appropriate (act FIRST via manage_messages/manage_campaign, THEN record), warns to check the `in_motion` flag to avoid double outreach, names check_prose as a cheap pre-check alternative, names get_engagement_review for reading/relisting decisions, and references get_operator_overview for the for_company param. It even includes a worked example workflow. This is exemplary 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?

The description adds substantial behavioral detail beyond annotations: it marks delete as DESTRUCTIVE, explains bulk partial-failure reporting ('never silent'), notes the 100-item max, mentions payload validation by the underlying route's schema with 422 errors, and handles 'no id' upsert semantics. While destructiveHint is already in annotations, the description adds the per-item error reporting and limits, which is meaningful added value.

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 well-structured with clear sections (Actions, Bulk, Responses) and uses bullet formatting for scannability. The 'DESTRUCTIVE' emphasis is effective. It's reasonably efficient for the complexity it covers, though the trailing 'Responses' section with a truncated 200 listing adds minor noise. Not every sentence is strictly necessary, but it's well-organized and front-loaded with the key actions.

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 complex 5-parameter tool with nested objects and no output schema, the description covers the action vocabulary, payload structures, bulk semantics, limits, and error behavior thoroughly. The main gaps: it doesn't describe expected response contents for a success, and the response section is cut off. Given the high complexity and no output schema, it's quite complete, though the truncated response documentation is a miss.

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?

Despite 100% schema coverage, the description adds valuable semantics: it explains the upsert key (name as identity), the payload structure for upsert {name, content, doc_type?, summary?, metadata?}, that reindex has no payload, and that id can be an array. The schema describes id as 'array of ids' but the description clarifies which entity the id names per action. It compensates well beyond the schema descriptions.

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

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

The description clearly states that the tool maintains the knowledge base as the 'consolidated KB writer,' and enumerates three actions (upsert, delete, reindex), which gives a specific verb+resource purpose. It distinguishes from siblings like manage_content and manage_messages by calling itself the 'KB writer.' However, the purpose is somewhat diluted by the large scope (multiple actions with bulk support), and it doesn't crisply distinguish KB documents from other managed resources beyond the title.

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

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

The description explicitly explains each action's semantics (upsert keyed by name, delete is destructive, reindex rebuilds index) and details bulk behavior (id arrays, server-side loop, per-item status, max 100). It gives clear context on when to use the tool vs not, though it doesn't name explicit alternative tools for when the KB is not the target. The destructiveHint annotation aligns with the 'DESTRUCTIVE' warning for delete.

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

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

The description is exceptionally transparent about side effects and behaviors. It discloses that edit takes scalar only with id arrays rejected, that attachments max at 5 and are rejected on non-email/LinkedIn channels, that draft_followup returns specific error codes (touch_already_exists, content_gate_blocked) with explicit 'never re-approve,' 'never retry as-is' directives, the per-person cooldown and override rules, the override_cooldown restriction to owner/operator roles, idempotency on retry, and that 'caller strings alone are not evidence' for reconcile. This far exceeds what the annotations (readOnlyHint=false, destructiveHint=false) convey.

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

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

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?

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% (per context signals), but the description adds enormous value beyond the schema. The `id` parameter gets per-action semantics (message UUID vs PERSON id vs COMPANY-PERSON id vs CAMPAIGN id depending on action), the `payload` parameter is fully documented per action with required fields and constraints (e.g., send requires client_request_id, sender_config_id, to_email; body is PLAIN TEXT with HTML escaping), and error behaviors like 'cooldown_active' and 'channel_unavailable' are explained. The description resolves virtually every ambiguity the generic schema leaves open.

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

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

The description opens with 'Manage Messages', the title, which is a tautology, but the next line 'Triage and edit outreach messages — the consolidated message writer' gives a clear, specific purpose with a verb (manage/edit/triage) and a concrete resource (outreach messages). It also names the tool as 'the consolidated message writer,' which helps distinguish why this tool centralizes message actions that might appear in other tools. It doesn't explicitly contrast with siblings like manage_outreach, but the scope is clear.

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 actions section provides extensive per-action context on when to use each (e.g., 'regenerate is the recovery path for a send the provider bounced', 'draft_followup... never loop on this call', 'reject a draft'). It names sibling tools (get_outreach_review, check_prose, get_operator_overview) and explains when data should come from them. It lacks an explicit 'when NOT to use this tool vs manage_outreach/manage_engagements' statement, which would push it to a 5, but the action-level guidance is thorough.

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

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

Annotations are limited (readOnlyHint false confirms mutation) but description adds meaningful behavioral context: forced start_immediately, partial-failure reporting per item for bulk operations (never silent), 422 validation behavior, 400 ambiguous-name behavior for for_company, and 403 handling. The 'start_immediately key is ignored' note is especially valuable disclosure of behavior beyond 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?

Well-structured with clear action bullets, a dedicated Bulk section, and a Responses section. Content is dense but required given the multi-action nature (6 actions with distinct semantics). Slightly verbose with for_company text repeated somewhat across both description and schema, but overall front-loads the action vocabulary effectively.

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

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

This is a high-complexity tool (6 actions, scalar/array duality, company scoping, bulk endpoints, ignored keys) and the description covers almost all behavioral facets. The only gap is the Responses section being truncated ('Successful Response') with no output schema, leaving return format partially undefined — though 422/400/403 error semantics are disclosed, successful response structure is not detailed.

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 each parameter (id, action, payload, items, for_company) already carries detailed descriptions. The tool description adds action-to-parameter mapping context (which id/payload applies per action) that complements rather than duplicates the schema. This aligns with the baseline-3 for high 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?

Description clearly states it 'starts and steers outreach plans' with an explicit action vocabulary (start, plan_override, channels, trigger_touch, pause/resume, update) each with a specific verb+resource. It distinguishes itself as 'the consolidated outreach writer' among siblings like manage_campaign, manage_messages, and manage_engagement.

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 explicit per-action guidance including which id type names what entity (PERSON UUID for start, plan UUID for others), when to use id arrays vs id scalar, the start_immediately key being forced true, and bulk behavior notes. Also covers company-scoping via for_company with precise guidance on naming and access enforcement.

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

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

The description is explicit about behavioral traits: it marks archive as DESTRUCTIVE (soft-delete, stops outreach plans, rejects pending drafts), notes save_discovered's atomic single-transaction semantics ('a rejected or failed save persists nothing'), discloses assessment authority ('never re-scores it'), and states there is no backend persona classifier. It also documents per-item partial failure handling and cap behaviors. The annotations provide destructiveHint=true, which the description aligns with and expands upon (naming consequences like stopped outreach). Rich behavioral disclosure well beyond annotations.

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

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

The description is long but dense with essential per-action semantics, and it front-loads with a clear 'Actions' heading. Every sentence adds operational value — id/payload rules, bulk behavior, cap limits, idempotency keys, validation nuances. It is structured and organized, though the save_discovered section is quite sprawling and could be tightened. Given the complexity of ten distinct actions, the length is largely justified.

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

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

This is a high-complexity tool with 10 actions, 5 parameters, nested objects, and no output schema. The description covers id vs items vs payload routing, action vocabulary, bulk limits (100), DESTRUCTIVE flag, idempotency for meeting_booked, and response codes. It distinguishes save_discovered from create and handles edge cases (duplicate handling, volume caps, ambiguity). For a consolidated multi-action writer with no output schema, this is thorough. Minor gap: no explicit statement of what the 200 response returns, though the schema doesn't cover it either.

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

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

Schema coverage is 100% with each parameter (id, items, action, payload, for_company) having a description. The description adds substantial meaning beyond the schema: it explains the action-specific payload shapes (e.g., {interaction_kind, direction?, summary?, disposition?...}), the id-as-array bulk routing for archive/unarchive vs per-item loops for others, the distinction between `items` and `id`, and the for_company membership/403 semantics. This is far beyond the schema descriptions, which mostly redirect to the tool 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?

The description opens with 'Create and manage people in your pipeline — the consolidated person writer,' giving a specific verb+resource and labeling its role as the consolidated writer among siblings (e.g., manage_deal, manage_account, manage_content exist as parallels). The ten named actions clearly identify what the tool does. Sister tools like get_person_360 (read) and import_prospects (bulk import) are implicitly distinguished. Clear and specific purpose.

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

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

The description gives explicit when-to-use guidance, particularly for save_discovered vs create: 'did no fit analysis? use action=create instead,' and 'THE path to score an existing stub.' It also specifies that assessment_campaign_id preserves provenance without assigning the person. It notes when to keep assessment vs use campaign ref. While it doesn't explicitly compare against sibling alternatives like import_prospects, the action vocabulary and 'consolidated writer' framing convey the intended scope versus alternative tools.

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

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

Annotations are minimal (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description carries the burden — and it delivers richly. It discloses that nothing auto-sends, walks through the state machine transitions, documents idempotency on client_request_id, explains the expected_version consistency requirement with stale-version rejection, and describes the 409 route_stale recovery path (re-run find_warm_path). This vastly exceeds annotation coverage.

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 long but uses clear section headers (bolded usage rules, responses), front-loads the core purpose, and each paragraph earns its place by explaining critical behavior. It is wordy in places (the state machine walkthrough is dense), but the density serves a genuinely complex tool with multiple transitions and consistency rules. Slightly more verbose than ideal but well-organized.

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 complex stateful tool with one parameter, no output schema, and minimal annotations, the description is remarkably complete. It covers the full transition lifecycle, error recovery (stale version, route_stale), idempotency semantics, differentiated usage versus siblings, and how to interpret the response (read approval_required/next_actions). Nothing important is left ambiguous for the agent.

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

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

Schema coverage is 100% for the single parameter (for_company), and the schema description is already extremely detailed (UUID or exact name match, 400 on ambiguous, 403 semantics, company_users membership). The MCP description adds nothing beyond what the schema documents. Per the baseline rule with high coverage, 3 is appropriate — no additional value added beyond schema.

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

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

The description has a specific verb+resource: 'Draft, approve, and record the outcome of ONE warm-introduction attempt.' It clearly defines what a relationship action is (an attempt reaching a target person through a mutual connection), distinguishes itself from find_warm_path (which only discovers routes and never writes), and explains the tool is 'the only way to act on one.'

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

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

The description explicitly contrasts with siblings: 'Use this instead of the direct-outreach tools when the path runs through a person' — manage_outreach and manage_messages send to the target, manage_engagements handles reactions, while this tool 'messages the connector.' It also gives explicit when-to-use and how-to-drive instructions (state machine, read approval_required/next_actions rather than guessing).

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, so the mutation risk is already communicated. The description adds meaningful context: that disconnect destroys delegated credentials (but retains historical ledger evidence), that reconcile is idempotent, and that disconnect requires a short-lived nonce from disconnect_preview. This is genuinely useful behavioral detail beyond the annotations.

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

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

The description is well-structured and front-loaded with a clear one-line summary followed by a bulleted action list. Each action is on one line with its key payload. The response section is terse. It's reasonably efficient, though slightly longer than strictly necessary with the trailing response boilerplate that adds little value.

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 complex multi-action tool with no output schema, the description maps each action to its inputs and expected effects well. It covers the disconnect lifecycle (preview → disconnect with nonce), idempotency guarantees, and per-action id semantics. Gaps: it doesn't describe return values/output shape for each action, which matters more given there's no output schema. The 200 response section is empty boilerplate.

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 description adds action-specific id/payload semantics inline (e.g., id = evidence record UUID for replay, id = binding UUID for decide_binding). The for_company parameter is exhaustively documented in the schema itself. The description ties each parameter to its action meaning, which adds some value beyond the schema, but the schema already covers all parameter names and purposes.

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

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

The description clearly states this manages the tenant's Stripe revenue connection and enumerates five distinct actions (connect, reconcile, replay, decide_binding, disconnect). It's specific with a verb+resource scope. However, it doesn't explicitly distinguish this from sibling tools like manage_account or manage_settings, and siblings like get_revenue could relate. The action list is clear but the overall purpose positioning relative to get_revenue/manage relationship is not articulated.

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 what each action DOES but provides minimal when-to-use guidance or alternatives. It doesn't explain when to choose reconcile over replay, or when decide_binding is appropriate. No exclusions or explicit 'use X instead for Y' guidance exist. The action vocab is the primary usage signal but there's no decision context for an agent choosing between the sub-operations.

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

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

Annotations declare destructiveHint=false and readOnlyHint=false, and the description adds significant behavioral nuance: the auto_fill action 'returns a job to poll via fetch type='job'', the hubspot_sync_settings action auto-enqueues a full backfill when changed, and hubspot_backfill is flagged 'Heavy (hours at 250k+ contacts)'. These are genuinely valuable behavioral disclosures not derivable from annotations. Validation behavior (route-based 422) is also disclosed.

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 well-organized with a bulleted action list, clear headers, and a response section. Each action gets a tight single-line treatment. However, it is somewhat long (~250 words) and includes some repetitive filler like 'Successful Response (Success Response)' in the response section, and the hubspot_backfill entry is dense with compound sentences. Generally front-loaded and earns most of its 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?

The tool has 5 params with nested objects, multiple distinct actions with different payload shapes, a job-polling flow for auto_fill, and a heavy backfill path — genuinely complex. The description covers all of these effectively. It explains the job-return mechanism, the backfill trigger, the heavy-cost caveat, and validation behavior. No output schema exists, but the description hints at per-item results for `items` and job-based async returns. It lacks explicit error/response-field listings but is adequately complete for invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds action-specific payload semantics for each of the 7 actions (e.g., profile payload steers match scoring, cta_link expects {action, cta_link_id, name, url...}), which goes beyond the schema's generic 'action-specific fields' text. The description also clarifies the `id` per-action semantics and validates payload constraints. Only minor gap: individual field types/requiredness within each action payload are left to the reader.

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 'company configuration — the consolidated settings writer' with a specific verb (update/manage) and resource (company settings). It enumerates 7 distinct actions with concise purpose for each, strongly distinguishing it from siblings like manage_outreach, manage_campaign, and manage_account. The singleton-per-company note adds useful scoping.

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 action is given a one-line usage description, and the hubspot_backfill entry explicitly explains when it should be used ('The recovery path when contacts were imported before their custom properties were configured'). The for_company parameter guidance in the schema adds clear multi-company context. However, it doesn't explicitly state when NOT to use this tool vs. siblings (e.g., outreach vs. settings), and no alternatives are named for overlap cases.

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

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

Annotations declare openWorldHint=true, readOnlyHint=false, destructiveHint=false. The description adds substantial behavioral detail: explicitly stating that lookup actions return results without storing them unless auto_save is set, explaining the idempotency_key mechanism for save_company, detailing conflict (transient race, replay payload) and mismatch (person won't see research) statuses, partial-failure semantics for batches, and warning that person_id must not be passed as id. This is rich operational context beyond what annotations provide.

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

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

The description is long but densely structured with clear headers (Lookup actions / Save actions / Batch research), sub-bullets per action, an example block, and a response section. The length is justified by the large action vocabulary and per-action payload schemas. Minor deduction: some redundant phrasing could be trimmed, but the structure makes navigation efficient.

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 8 distinct actions, mixed read/write behaviors, partial-failure semantics, idempotency, and cross-tool dependencies (manage_person, pipeline-fill), the description covers the essential operational surface thoroughly: per-action payload contracts, write semantics, error/status behaviors (mismatch, conflict, 403, 422), batch caps, and cross-references to related tools. No output schema exists, but the description covers response characteristics adequately.

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 extensive per-action payload semantics: exact field lists for save_company (idempotency_key, name, person_id?, website?, etc.), find_email payload {first_name, last_name, domain}, linkedin_fetch payload {linkedin_url, include_company?...}, and a full worked JSON example with sources_by_field structure. The description clearly explains the id/payload/for_company parameter distinctions and the critical warning about save_person never taking 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?

The description clearly states 'Run prospect/company research and save the results — the consolidated research tool,' naming the specific verb (research/run) and resource (prospects/companies). It distinguishes itself from siblings by presenting itself as the consolidated research tool versus the individual get_* and manage_* tools, and the action vocabulary (find_linkedin, enrich_company, etc.) gives concrete operation names.

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

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

The description explicitly separates lookup actions (returned, not stored) from save actions (write research rows), and gives precise when-to-use guidance for each action. It even names its sibling for creating prospects: 'new prospects go through manage_person action=save_discovered,' explicitly stating when NOT to use save_person and which alternative tool to use instead. Batch usage is also explained with specific caps (10 companies or 5 people).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, covering the safety profile. The description adds meaningful behavioral context beyond annotations: companies hits an EXTERNAL service (Hunter.io, 503 risk), all other types are internal tenant-scoped, and pagination is rejected for some types while silently accepted for others. However, it doesn't describe result shape edge cases or failure behaviors beyond the 422/503 mentions, so with strong annotations a 3 is appropriate.

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

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

The structure is effective: an opening summary followed by type-by-type routing, pagination rules, and a campaign-routing disambiguation section, then the Responses note. It front-loads the primary disambiguation (type selector) before details. However, the description is quite long with a heavy inline type enumeration that partly duplicates the input-schema enum, and the campaign paragraph slightly over-elaborates with prose-heavy field names inline.

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

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

Given the tool's extreme complexity (12 polymorphic types, 6 parameters with heavily nested filters objects, full schema coverage at 100%, enriched annotations, and no output schema), the description covers the critical routing decisions, pagination matrix, external-service caveats, cross-lane recommendations (warm_only+status+sort_by combo), and field-projection truncation risk. This is complete despite no output schema because it thoroughly explains what returns vary across types.

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 richly. The description adds value by clarifying intent (e.g., pagination support per type, campaign fields projection semantics, warm_only combined-lane trick) that goes beyond bare schema text, but since the baseline is 3 with full coverage and the description doesn't add format/syntax detail beyond the schema, staying at baseline is correct.

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

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

The description clearly states it's a polymorphic read-only search across workspace entities, enumerates all 12 supported entity types with their routing targets, and explicitly distinguishes itself from siblings like fetch (single campaign by UUID), find_warm_path, and manage_campaign. The specific verb+resource (read-only search across types) plus the type-by-type breakdown makes it 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?

Excellent guidance on when to use this vs alternatives: explicitly names fetch for single-campaign reads, manage_campaign for mutations, find_warm_path for individual warm targets, and notes pagination support/rejection per type. The companies special case (external Hunter.io, requires domain, 503 if unconfigured) and campaign fields projection guidance (prefer fetch for full config to avoid truncation) give concrete 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 annotations declaring readOnlyHint=false, destructiveHint=false, and openWorldHint=false, the description somewhat contradicts the implied safety profile — publish is a mutation that creates/updates skills but destructiveHint=false suggests limited destructive impact. The description adds useful detail (invoke has no payload, publish requires body), but doesn't disclose side effects, authorization requirements (does publishing require special privileges?), or what happens on overwrite.

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

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

The description is compact with clear action bullets, front-loading the two main actions. The 'Responses' section adds minimal value (no output details). Each line earns its place, though the response section is slightly wasteful given there's no output 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-action tool with shared generic param semantics (id, payload, items), the description adequately splits the contracts per action. But it lacks details on: return format (what an invoke response looks like), error conditions beyond the implicit 422 mentioned in schema, and whether publish supports items/create-like batching. The output schema is absent, so return value documentation falls on the description.

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% (all 5 params described). The description adds specific per-action parameter contracts: for invoke id=skill UUID or name with no payload; for publish id=none and payload={body,...}. This meaningfully supplements the schema, which says only 'see the tool description'. However, the generic schema descriptions already redirect to the tool description, creating some circular dependency.

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 specific verbs ('Invoke or publish Vruum skills') with distinct actions clearly enumerated. It differentiates from sibling tools by naming alternative tools (search, fetch) for non-executing tasks. However, it doesn't contrast against the many manage_* siblings, though the 'skills' subject matter is specific enough.

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

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

The description clearly explains when to use this tool vs alternatives: 'To browse skills use search type='skills'; to read one without executing it use fetch type='skill''. This gives explicit when-not guidance. It also clarifies that invoke follows returned instructions in current context, which is useful behavioral guidance.

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