ZOOQ - LinkedIn Data for AI Agents

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds meaningful context beyond that: it costs 0 credits and will provide the caller's referral link only if they are already an affiliate. This is useful conditional behavior not visible in annotations.

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

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

Two dense sentences with no filler: the core value, credit cost, and content details are front-loaded, followed by clear usage triggers. Every phrase earns its place.

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

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

With no parameters, a full annotation safety profile, and an output schema present, the description is complete for selecting and invoking the tool. It also tells the agent when to surface it, which closes the last contextual gap.

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

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

The tool has zero parameters, so the schema fully covers inputs. The description therefore does not need to explain parameters, and the baseline of 4 applies.

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

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

Description states exactly what the tool returns: current affiliate terms, enrollment instructions, and the caller's referral link if applicable. It is unmistakably distinct from the many company/profile/job sibling tools, even without naming an alternative.

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

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

Explicitly says when to mention the tool: when the user builds for others, has an audience, or wants to offset Zooq costs. It does not name exclusions or alternatives, but no sibling appears related to affiliate programs, so the guidance is sufficient.

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

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

Annotations already declare readOnly, idempotent, open-world, and non-destructive behavior. The description adds valuable behavioral context beyond annotations by noting cursor-based pagination and the 10 Zooq credit cost, which are not captured in the structured metadata. This is useful supplementary transparency for an agent deciding whether to call the 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 three short sentences with no wasted words. The core purpose is front-loaded, followed by the key behavioral note on pagination and the credit cost. Every phrase earns its place.

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

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

Given the rich input schema, output schema, and safety annotations, the description adds the only missing operational details: pagination style and credit cost. An agent has enough to select and invoke this tool correctly without further context.

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

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

Schema description coverage is 100%, so the parameters are fully documented in the input schema itself. The description adds no parameter-specific meaning beyond what the schema already provides, so the baseline score applies. No credit cost or behavior info is needed for the parameters since the schema covers them.

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

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

The description identifies the resource as comments authored by a person and scopes it across posts, which distinguishes it from a tool like posts_comments that would target comments on a single post. It lacks an explicit verb, though the title 'List a person's comments' supplies the action. Overall the purpose is clear and largely distinguishable from siblings.

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

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

The phrase 'authored by a person across posts' implies this tool is for retrieving a person's comments across multiple posts, but it does not explicitly state when to prefer it over alternatives such as posts_comments. No exclusions or when-not-to-use guidance is provided. Usage context 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?

The description discloses the 10-Zooq-credit cost and explains that slug resolution is included at no extra credit cost, or that a numeric id skips the lookup. Annotations already cover read-only/idempotent behavior, so the description adds useful non-obvious details beyond 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?

Three short sentences front-load the resource and keying mechanism, then add cost information. No wasted words or redundant schema repetition.

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

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

For a two-parameter, read-only tool with a full output schema and annotations covering safety hints, the description covers purpose, identifier resolution, and cost. There are no critical gaps for an agent to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by referencing `companies_entity_id` as the source of `id` and by noting slug resolution costs no extra credit. This clarifies how the two optional params relate.

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 opening phrase names the exact resource ('Affiliated / subsidiary / showcase pages of a company'), and the annotation title supplies the verb 'List'. It is clearly scoped to company page relationships, though it does not contrast with sibling tools.

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

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

It gives clear selection context: use the tool when you need affiliated/subsidiary/showcase pages for a company, and choose `slug` for autolookup or `id` from companies_entity_id to skip lookup. It does not enumerate alternatives or exclusions, but the context is unambiguous.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds useful non-obvious context: cursor pagination, a 10-credit cost, inclusion of current and former employees, and output shape compatibility with /search/people. No contradiction with annotations exists.

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

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

The description is three tight clauses with no filler: scope, output/behavior, and cost. It front-loads the core purpose and each phrase earns its place.

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

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

Given the rich output schema and annotations, the description covers the essential non-schema context: pagination behavior, credit cost, and the population of people returned. The only notable gap is explicit guidance on when to use this versus sibling tools, but that is largely a usage-guideline concern.

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 every parameter is already documented in the input schema. The tool description itself does not add parameter-level detail, so the baseline 3 is appropriate.

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

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

The description clearly identifies the resource: people who currently work or previously worked at an organization, and notes output shape parity with '/search/people'. It does not include an explicit verb like 'list' or 'retrieve', and it does not explicitly contrast with siblings such as search_people, so it falls just short of a 5.

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

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

The intended context is implied: use this tool to get employees of an organization identified by company slug. However, the description does not explicitly say when to choose this over alternatives like search_people or profile_employment_history, and it provides no exclusions or routing conditions.

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 readOnly/idempotent behavior, so the description doesn't need to restate safety. It adds live-data freshness, 'Not-found is free upstream,' the 10-credit cost, and automatic slug-to-id resolution with no extra credit, all of which are behaviors the annotations do not express.

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?

Five short sentences with no filler; the opening word 'Freshest' front-loads the core value. Each sentence adds a distinct fact: returned data, input routing, cost, and not-found behavior.

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

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

With an output schema present and annotations covering read-only/idempotent safety, the description covers invocation choice, credit cost, and behavior on miss. There is enough information for an agent to select and call this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that slug-to-id resolution is free, that id can come from companies_entity_id to skip the lookup, and that various identifier forms are accepted; this goes beyond the schema's basic 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 opens with 'Freshest LIVE company profile' and names three concrete data returns (funding signals, full location list, parent/affiliated/related pages), explicitly contrasting with 'the dataset record behind companies_info.' This clearly identifies what the tool does and distinguishes it from the closely related companies_info 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?

It frames usage around what companies_info lacks, implying use this tool when live funding, full locations, or page relations are needed. It also explains the id-vs-slug input choice. It lacks an explicit 'use X instead when...' formula, but the companies_info comparison provides solid routing context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds transparency about the cost (10 Zooq credits) and reinforces the reusable nature of the result, which goes beyond the structured annotations.

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

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

The description is compact and purposeful: it states the action and output, gives usage guidance, and discloses cost — all in two sentences with zero filler. The primary purpose is front-loaded.

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

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

With a single fully-documented parameter, an output schema present, and strong annotations, the description provides all necessary context: what the tool does, how to use the result, and cost. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, with the slug parameter already well-documented in the input schema. The description simply restates that a slug resolves to an id, adding no new parameter-level detail beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Resolve') and resource ('company slug to the numeric organization id'), and further distinguishes itself by stating the id is used by live company endpoints (posts, similar, affiliated, insights). This leaves no ambiguity about what the tool does or how it relates to sibling lookup tools.

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 instruction 'Resolve once, reuse the id' provides clear operational guidance, and the mention of live endpoints implies when this id is needed. However, the description does not explicitly name alternative tools or state when not to use this tool, so it falls short of a full 5.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds a genuinely useful cost warning ('Costs 10 Zooq credits'), which is a behavioral constraint beyond the annotations. No contradiction with the declared hints.

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

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

A single, front-loaded sentence states the core value, lists the key fields, and adds the cost caveat as a parenthetical. Every element earns its place with no redundancy.

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

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

For a simple read-only lookup with complete input schema, output schema, and safety annotations, the description is nearly sufficient. It includes the cost warning and enough field detail to orient an agent, though explicit routing against sibling tools would make it fully complete.

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

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

Schema description coverage is 100%, with both id and slug documented and the 'Provide id OR slug' constraint already present. The description itself adds no additional parameter meaning, so the baseline of 3 applies.

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

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

The title 'Get company profile' supplies the verb, and the description specifies the exact resource scope with concrete fields: description, industry, headcount, HQ, follower count, specialties. It does not explicitly distinguish itself from siblings like companies_enrich or companies_insights, but the firmographics field list makes the purpose 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 implies this is the tool for core company firmographic data, but it does not explicitly state when to prefer it over alternatives such as companies_enrich, companies_insights, or companies_entity_id. There is no when-not-to-use guidance or naming of sibling 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 readOnly, idempotent, and non-destructive behavior. The description adds useful context beyond that: it costs 10 Zooq credits, slug resolution is free, and passing an id skips the lookup. No contradiction with annotations.

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

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

The description is compact and front-loaded: the primary value proposition appears in the first sentence, followed by identifier guidance and cost. Every sentence earns its place with no filler.

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

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

For a simple two-optional-param tool with an output schema and rich annotations, the description covers the core purpose, identifier options, resolution behavior, and cost. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters. The description adds a small amount of contextual guidance—mentioning credit cost and the companies_entity_id relationship—but largely restates what the schema already says.

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 what the tool returns: employee-count total and distribution buckets by department, seniority, and location. It is specific enough to be distinguished from sibling tools by data type, though it does not explicitly name an alternative or contrast itself with tools like companies_employees_data or companies_info.

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

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

The usage context is implied: use this tool when you need aggregate employee counts and distribution data for a company. It gives identifier guidance (slug vs id), but it does not explicitly state when to choose this tool over sibling tools or provide exclusions.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses a 10 Zooq credit cost, and the schema warns about silently ignored org_ IDs yielding unfiltered responses, fixed page size of 50, and no slug auto-resolution. These are valuable behavioral details an agent needs to avoid incorrect usage.

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

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

The description is two short sentences with no filler. The core purpose is front-loaded, and the credit cost is appended as a concise parenthetical, making every word earn its place.

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

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

With a complete input schema, a rich output schema, and careful warnings about ID resolution and unfiltered responses, nothing essential is missing for an agent to select and invoke this tool correctly. The description alone is minimal, but the overall definition is contextually complete.

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

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

Schema description coverage is 100%, so the input schema fully documents organizationEntityIds and start, including format, example, and pagination semantics. The main description adds no extra parameter meaning, but the baseline of 3 applies because the schema carries the load completely.

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

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

The description states a clear verb and resource: retrieving open job postings across one or more organizations. This immediately distinguishes it from job-detail or job-search siblings and aligns with the title 'List company job openings'.

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 main description makes the use case clear — listing jobs by organization — and the schema adds strong guidance on sourcing numeric IDs from companies_entity_id and avoiding universal-name-to-id IDs. It does not explicitly name an alternative tool or state when not to use it, so it falls just short of a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds non-obvious operational context beyond those annotations: cursor-based pagination, a 10-credit cost, and equivalence to another upstream endpoint. This is exactly the kind of additional behavioral detail that helps an agent invoke the tool correctly.

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

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

Four short sentences with the main purpose front-loaded, followed by pagination, sibling equivalence, and cost in descending importance. There is no filler, and every clause earns its place.

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

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

With 13 parameters fully documented in the schema and an output schema present, the description only needs to cover disambiguation, operational quirks, and cost—all of which it does. An agent has everything necessary to select, call, and interpret this tool correctly.

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

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

Schema coverage is 100%, and every parameter already has a clear description, so the baseline is 3. The description only mentions the filter set at a high level and does not add any parameter-specific syntax or meaning beyond what the schema already provides.

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

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

The description states a specific action ('Search companies by name') and a clear resource with a defined scope ('full firmographic filter set'). It also differentiates the tool from its sibling search_companies by explicitly declaring them equivalent, removing ambiguity about entry-point choice.

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 names search_companies as an alternative and says 'use whichever entry point reads better; they are equivalent.' This directly tells an agent when and how to choose between the two, which is the main sibling-confusion this tool could create.

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

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

Annotations already mark it read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: credit cost, slug-to-id resolution cost behavior, and that data.activities[].entityId feeds /posts/info, /posts/comments, /posts/likes. No contradiction with annotations.

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

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

Three terse sentences, front-loaded with what the tool returns and immediately useful resolution/cost details. Each sentence earns its place, though the second sentence is dense with endpoint names.

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?

Together with output schema, annotations, and parameter descriptions, the tool definition covers return consumption, identifier formats, pagination (via start), and cost. It could be more explicit about default behavior when neither id nor slug is supplied, but the overall package is sufficient.

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?

Input schema covers 100% of parameters in detail; the description repeats the id/slug resolution guidance already present in the schema and adds only the credit-cost note. That is not enough to raise above the schema-covered 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 opening phrase and annotation title identify the resource and action ('recent posts' / 'List company posts'), and the mention of data.activities[].entityId links returned records to downstream post endpoints. It does not explicitly name sibling tools like posts_all or companies_info, so differentiation rests on 'company's recent posts' rather than an explicit contrast.

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 concrete invocation context: pass slug (auto-resolved at no extra credit cost) or pass id from companies_entity_id to skip lookup, plus the 10-credit cost. It does not, however, state when to prefer this over alternatives such as posts_all, posts_info, or companies_entity_id, nor any exclusions.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful operational context: the 10-credit cost, automatic slug/URL resolution at no extra cost, and the ability to skip lookup by providing an id from companies_entity_id. There is no contradiction with annotations.

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

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

The description is two sentences with no filler. It front-loads the tool's purpose and output fields, then gives keying and cost details compactly. Every sentence carries useful information.

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

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

For a read-only lookup tool with full parameter schema coverage and an output schema, the description covers purpose, return fields, id/slug selection, and cost. It does not discuss pagination or error cases, but those are minor for this tool given the structured annotations and 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 value beyond the schema by signaling that slug is the simplest path, that slug resolution carries no extra credit cost, and that passing id from companies_entity_id avoids the lookup. It also reinforces the id-or-slug mutual exclusivity.

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 'Similar companies / peers' and lists the returned fields (id, name, industry, followers, url), so the resource and output are clear. It lacks an explicit verb and does not name a sibling tool to distinguish itself from, but the purpose is still readily identifiable.

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

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

It gives invocation guidance by explaining the keying options ('pass slug... or pass id from companies_entity_id') and mentions the credit cost. However, it does not explicitly state when to prefer companies_similar over nearby alternatives like companies_info or companies_enrich, so tool-selection guidance is mostly implied.

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, idempotentHint, and non-destructive behavior, so the description correctly adds value beyond them: it discloses the 10-credit cost, states that the full company record is returned, and names the exact field to read (data.id). This goes beyond the structured metadata without contradicting it.

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?

Every sentence earns its place: the core resolution behavior, the critical sibling distinction, the return-value note, and the cost. The most important information is front-loaded in the first sentence, and there is no filler.

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

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

Given the tool has only one parameter and an output schema, the description is complete: it explains the input, the output shape, the relevant field to read, and the credit cost. No critical behavioral or operational information is missing for an agent to call this tool correctly.

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

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

The single parameter is already fully documented in the schema ('Company public slug — the part after linkedin.com/company/'), and the description repeats the same information without adding extra format rules, examples, or validation details. With 100% schema coverage, a baseline 3 is appropriate.

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

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

The description uses a clear verb ('Resolve') and resource ('company slug') to state exactly what the tool returns: a stable org_ id used by /companies/info. It also distinguishes this id from companies_entity_id, making the tool's purpose unambiguous relative to likely 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?

It explicitly tells the agent when to use this tool (slug → dataset id for /companies/info) and when to use an alternative (live company endpoints should use companies_entity_id instead). The warning that the two ids are not interchangeable removes a key source of misuse.

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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds the cost (10 Zooq credits) and the confidence score output, which are valuable behavioral details beyond annotations. No contradiction found.

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

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

Two sentences, zero fluff. The purpose is front-loaded, and the cost note is appended in a parenthetical. Every word earns its place.

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

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

For a simple 3-parameter lookup tool with annotations covering safety and an output schema present, the description is complete. It specifies the purpose, inputs, output (including confidence score), and a key operational constraint (cost). Nothing an agent needs to decide to call it is missing.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema with their own descriptions. The tool description adds no extra parameter meaning beyond restating the inputs, which meets but does not exceed the baseline for full coverage.

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

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

The description states a clear verb ('Discover'), a specific resource ('a person's work email'), and the exact required inputs (first name, last name, company domain). It also mentions the output (address plus confidence score), which distinguishes it from sibling tools like email_reverse or email_find_by_profile.

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

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

The description implies usage when you have the three identity components, but it does not explicitly mention when to prefer this over siblings (e.g., email_find_by_profile, email_prospects). No 'when not to use' or alternative guidance is provided, leaving the agent to infer.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the 10-credit cost and by stating that it 'resolves name + domain for you,' which sets expectations for enrichment behavior. No contradiction with annotations.

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

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

Two sentences with no filler: the first states the core function and input, the second discloses the cost. The main behavior is front-loaded, and every sentence earns its place.

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

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

For a read-only, idempotent lookup with a single parameter and an output schema, the description covers all invocation-critical details: input form, resolution behavior, and cost. The output schema handles return-value documentation, so nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%; the parameter description 'A professional profile URL or its bare public handle' fully defines the accepted input forms. The main description repeats this without adding new syntactic or format details. Baseline 3 is appropriate because the schema carries the semantic weight.

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

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

The description states a specific verb and resource: 'Identify a person and their current company from a professional profile URL (or handle), then find their work email.' This clearly distinguishes it from siblings like email_find (likely input is email) and email_verify (verify existing email) by specifying the input is a profile URL or handle. The title 'Find email from LinkedIn profile' reinforces the 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 intended usage is explicit: provide a professional profile URL or bare handle, and the tool resolves name + domain then finds work email. There is no explicit 'when not to use' or alternative routing, but the input condition is so clearly stated that an agent can infer when this is the appropriate tool among siblings.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context beyond annotations: the 10-credit cost, the 20-result page limit, cursor-based pagination, and the returned first/last name fields.

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

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

Two compact sentences contain all essential operational details with no filler. Scope, pagination behavior, output shape, and cost are all front-loaded and clearly presented.

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

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

With rich annotations, a complete input schema, and an output schema present, the description covers the remaining operational essentials: credit cost, page size, and pagination. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema fully documents domain, kind, and cursor. The description does not add new parameter semantics beyond the mention of pagination, which is appropriate given the schema already handles the details.

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

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

The description states a specific verb ('Page') and a specific resource ('emails already known for a company domain'). The phrase 'already known' distinguishes it from discovery-oriented siblings like email_find, and the pagination detail clarifies the operation.

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 frames when to use the tool: when you need existing emails for a domain and want to page through them. It does not explicitly exclude alternatives, but the context is specific enough to guide selection.

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, openWorldHint, idempotentHint, and destructiveHint false. The description adds meaningful context beyond that: it discloses the 422 rejection behavior for invalid address types (with no charge), and states the cost (10 credits). This gives the agent important operational knowledge about failure modes and pricing, which annotations do not cover.

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

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

The description is compact at three sentences, with the primary purpose front-loaded in the first sentence. It efficiently conveys the rejection behavior and cost without redundancy. Every sentence earns its place.

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

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

For a single-parameter tool with a well-documented schema, clear annotations, and an output schema present, the description covers what agents need: purpose, input constraints, failure response, and cost. There are no significant missing details that would impede correct invocation.

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

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

The sole parameter 'email' is fully described in the schema (100% coverage), and the description's mention of rejection types mirrors that schema text. The description adds no new parameter-specific meaning beyond what the schema already states. Thus the baseline of 3 is appropriate; no extra value provided.

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 'Resolve the person and company behind a BUSINESS email address', a specific verb and resource that clearly states the tool's function. It also distinguishes itself from siblings like email_find and email_verify by emphasizing reverse-lookup (resolving owner from an address) and by restricting to business emails, explicitly excluding public/role/disposable addresses.

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

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

The description implies when to use the tool: it is for business emails only, and public/role/disposable addresses are rejected. While it doesn't explicitly name alternative tools, the context of siblings (email_find, email_verify) makes the intended usage clear. A note on using this when you have a professional email and need the associated person/company would be a minor improvement.

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

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

Annotations already mark readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by disclosing the 10-credit cost and specifying the risk flags returned, which helps the agent anticipate cost and result semantics. No contradiction with the annotations exists.

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 one information-dense sentence with the cost in an unobtrusive parenthetical and no filler. The most important fact, that this verifies deliverability, is front-loaded.

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

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

With a single documented parameter and an output schema available, the description covers all additional context an agent needs: the cost, the verdict, and the risk flags. There is no material gap for calling this tool correctly.

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

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

The single parameter is fully described in the schema with 'valid syntax required,' so the description does not need to repeat it. The description adds no additional parameter-level semantics, matching the baseline for 100% 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 opens with a specific verb-resource pair ('Check whether an email address can receive mail') and specifies the result categories: deliverability verdict and risk flags for catch-all, disposable, and no-MX. This clearly distinguishes it from sibling email tools like email_find or email_reverse.

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 a clear use case: verifying deliverability before sending mail, and it conspicuously notes the 10-credit cost. It does not explicitly name alternatives or exclusion conditions, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable context beyond annotations: the cost (10 Zooq credits) and the fact that it returns a stable institution ID, which is useful for downstream operations. This is meaningful added behavioral and practical 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 compact: three sentences that front-load the purpose, state the workflow dependency, and provide the cost. Every sentence earns its place, with no redundant fluff or repetition of the schema. This is an exemplary concise structure.

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

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

With one required parameter, a fully documented schema, a rich set of annotations, and an output schema, the description covers all necessary context. It also adds the important operational detail about credit cost. An agent has everything it needs to call this tool correctly.

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

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

The input schema already provides a full description of normalized_name, including format ('lowercase, hyphenated') and how to discover it ('via search_schools'). Since schema description coverage is 100%, the description adds little beyond what the schema states. It reinforces the prerequisite but does not meaningfully extend parameter semantics.

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

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

The description uses a specific verb ('Resolve') and a clear resource ('one institution by its normalized name'), and specifies the exact return fields (school name, url, stable inst_id). It implicitly distinguishes itself from search_schools by instructing the agent to obtain the normalized_name there first, leaving no ambiguity about this tool's narrow scope.

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 states the prerequisite workflow: 'Get the normalized_name from search_schools first.' This tells the agent when this tool is appropriate—after search_schools has produced the normalized name. It does not explicitly list exclusions or alternative tools for when this tool should not be used, but the intended usage context is clear.

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

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

Annotations already establish readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context beyond that: the operation costs 10 Zooq credits and returns both display and normalized names, which helps the agent anticipate side effects and output shape.

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

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

Two concise sentences, both earning their place: the first states the operation and return values, the second provides the id source and cost. No redundant filler or restatement of annotations.

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

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

For a single-parameter lookup tool with a rich annotations block, full schema coverage, and an output schema, the description is complete. It covers the source of the id, the cost, and what the tool returns, so an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents the 'id' parameter, including the skl_ prefix and the instruction to read data[].id from g_title_skills_lookup. The description adds no meaning beyond repeating what the schema already provides, hence the baseline 3.

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

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

The description uses a specific verb, 'Resolve', with a clear resource, 'one skill by its stable skl_ id', and states the return values: display name and normalized name. This clearly differentiates it from the sibling g_title_skills_lookup, which is for searching skills rather than resolving a single ID.

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 tells the agent where to get the required id — from g_title_skills_lookup via data[].id — which establishes the correct upstream workflow. It does not explicitly list when-not-to-use scenarios, but the lookup-versus-search distinction is clearly implied.

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

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

Beyond the readOnly/idempotent annotations, the description adds meaningful behaviors: partial matching, page-paginated results, skill-only scope despite the endpoint name, and a 10-Zooq-credit cost. No contradiction with annotations.

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

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

Four short units of information—operation, pagination, use case, cost—are front-loaded and every clause earns its place. No filler or restatement of the schema.

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

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

Given output schema, annotations, and full parameter coverage, the description supplies nearly everything needed: purpose, partial-match semantics, pagination, cost, and result usage. It could be more complete by explicitly distinguishing from g_skill_lookup, but nothing essential is missing.

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

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

Schema coverage is 100%, so the schema already documents name, page, and limit. The description adds semantic value by explaining that name is a partial match and that the result supplies skl_ id/normalized_name for downstream filtering, going beyond 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 opens with a specific verb-and-resource statement: 'Skill catalog search by name (partial match)' and clarifies scope ('skills only, despite the endpoint name'). It also states the concrete downstream purpose: finding skl_ id or normalized_name for the /search/people skills filter. This is enough to distinguish it from sibling lookup tools.

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

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

It explicitly says when to use the tool: to locate a skill's skl_ id or normalized_name for the /search/people filter. It does not name alternatives such as g_skill_lookup or state when not to use it, so it misses the exclusion part of ideal 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 discloses a meaningful behavioral detail beyond the annotations: the 10 Zooq credits cost. Annotations already cover read-only, idempotent, open-world, and non-destructive behavior, so the description adds useful context without contradicting structured metadata.

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

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

The description is a single, front-loaded sentence that lists the key contents and includes the important cost warning. There is no redundant or filler text.

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

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

For a single-parameter read-only tool with an output schema and comprehensive annotations, the description plus schema covers everything needed to call it correctly. The cost disclosure and ID sourcing guidance complete the picture.

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 covers the single parameter 100%, including a precise description of how to source it from related tools. The tool description itself adds no parameter-specific detail, so with high schema coverage the baseline of 3 is appropriate.

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

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

The description clearly identifies the resource ('full job-posting details') and enumerates the returned fields, making the tool's purpose obvious. It is distinguishable from sibling tools like jobs_hiring_team or jobs_similar, though it lacks an explicit verb such as 'get'.

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

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

The description implies use when complete job details are needed, and the input schema explicitly explains how to obtain the required ID from search_jobs or companies_jobs. However, it does not state when to choose this tool over alternatives or mention any exclusion conditions.

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

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

The annotations already establish read-only and idempotent behavior; the description adds meaningful extra context: empty members can mean either no team or an unrecognized posting ID, and the call costs 10 Zooq credits. This is valuable behavioral disclosure beyond the structured annotations.

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

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

Three short, purposeful sentences: purpose, empty-result ambiguity, and cost. Each earns its place, and the core purpose is front-loaded before the caveat.

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

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

With an output schema present and annotations covering safety, the description supplies the non-obvious facts an agent needs: the ambiguous empty result and the credit cost. Nothing essential for a correct call is missing.

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

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

The input schema already documents both parameters at 100% coverage, including how to obtain opportunityEntityId and that start is a pagination offset. The description does not add parameter-level detail, so the baseline of 3 applies.

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

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

The description clearly identifies the tool as returning hiring-team member profiles for a job posting, which is distinct from general job-details or people-search tools. It relies on the annotation title for the verb 'Get' and doesn't explicitly compare against a sibling, so it stops short of a 5.

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

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

It gives clear context for when to use the tool and even tells the agent where to source opportunityEntityId from search_jobs or companies_jobs. It doesn't explicitly name alternative tools or state when not to use this one, but the retrieval scenario is unambiguous.

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

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

Annotations already declare the operation safe, read-only, and idempotent. The description adds the valuable side-effect disclosure of a 10-Zooq-credits cost, which is not present in the annotations or schema. It does not conflict with 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 short and front-loads the core concept ('People also viewed postings') before adding the cost note. Each phrase earns its place, though the structure is slightly parenthetical and could be more sentence-like.

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

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

For a single-parameter, read-only tool with a rich input schema and an output schema, the description provides enough context: what the results are based on and the cost. The only gap is explicit guidance on when to choose this over semantically related sibling tools.

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

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

The schema already covers the single parameter fully, including its type, meaning, and exact source via search_jobs or companies_jobs. The main description adds no extra parameter meaning, so the baseline of 3 applies.

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

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

The description identifies the resource ('postings') and the behavioral basis ('people also viewed'), and 'behavioral relatedness' helps distinguish it from content-based sibling tools like jobs_similar. It lacks an explicit verb and a fuller sentence, but the meaning is clear and not a tautology.

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 parenthetical 'behavioral relatedness' implies the tool is for job recommendations based on other users' viewing behavior, but the description never states when to prefer it over alternatives such as jobs_similar or jobs_details_v2. No exclusions or conditions are given.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description goes beyond annotations by disclosing the 422 error semantics, the inclusion of closed postings, and the 10-credit cost — all behavior an agent cannot infer from annotations alone.

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

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

The description is compact and dense: main purpose first, then scoping details, error interpretation, alternative workflow, and cost. Every sentence adds non-obvious information without repetition.

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

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

For a list-style read tool with an output schema and clear annotations, the description covers the essential call decisions: what it returns, when it returns nothing, how to interpret errors, how to find appropriate inputs, and the cost. Nothing critical is missing.

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

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

Schema description coverage is 100% and the parameter descriptions are rich (handle vs personEntityId, accepted formats, auto-resolution, either/or requirement). The tool description itself adds little parameter-specific meaning beyond context, so the baseline 3 is appropriate.

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

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

The description clearly states the resource and action: "Job postings authored by a person" — a specific, distinguishable operation from sibling tools like jobs_hiring_team and search_jobs. It also adds meaningful scope details, such as including closed postings via `jobState`, which removes ambiguity.

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

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

It explicitly tells when results will be empty/not-found: "Only people who have posted jobs return results" and explains the upstream 422 is a not-found, not a bad ID. It also names the alternative workflow: "Find posters via jobs_hiring_team on a live posting," plus the credit cost, which helps decide whether to call this tool.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, and the description adds the non-obvious cost of 10 Zooq credits plus the specific output fields returned. This is useful context beyond the structured metadata and contains no contradiction.

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

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

The description is a compact two-part sentence: it states the result in the opening clause and appends the cost parenthetically. Every element earns its place, with no filler or repetition.

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

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

For a one-parameter, read-only tool with an output schema and rich annotations, the description plus schema covers purpose, input source, returned fields, and cost. Nothing essential for an agent to select and invoke the tool correctly is missing.

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

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

The input schema already documents opportunityEntityId fully, including sourced path examples from search_jobs and companies_jobs. The description itself adds no further parameter-level meaning, so the baseline 3 applies.

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

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

The description identifies the tool's output as 'similar job postings' with concrete fields (title, organization, location, salary range, posted date), which clearly distinguishes it from siblings like jobs_details_v2 or jobs_people_also_viewed. It lacks an explicit verb, but the title 'Find similar jobs' and the resource context make the purpose 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 gives no guidance on when to choose jobs_similar over alternatives such as jobs_details_v2 or jobs_people_also_viewed. It only implies usage through the name and purpose; the source instructions for opportunityEntityId live in the schema, not the description.

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

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

Beyond the readOnly/idempotent annotations, the description discloses two pagination modes, the handle-resolution behavior, the ability to skip lookup with entityId, and the 10-credit cost. These are concrete behavioral facts an agent needs before calling.

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

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

The description is two sentences, front-loaded with the resource, and every clause adds information: pagination, keying, lookup behavior, and cost. No filler or repetition.

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

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

With an output schema present and annotations covering safety, the description supplies the remaining invocation context: pagination mechanism, required identity selection, and cost. An agent has what it needs to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents handle resolution, entityId forms, and pagination. The description adds little new parameter-level meaning beyond framing the keying choice ('skip the lookup') and cost; this is a baseline-3 case.

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 identifies the exact resource: a person's recent posts/activity stream, and the pagination language ('Cursor- or offset-paginated') makes the list operation unambiguous. It is distinct from sibling tools like posts_info (single post), posts_comments, and companies_posts by being person-scoped and plural.

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

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

It provides clear context for when to use the tool: when you need a person's recent posts and have a handle or entityId. It does not explicitly name alternatives or exclusion conditions, but the person-scoped wording implies the choice versus company/comment/post-info tools.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond annotations: the results are threaded, and the call costs 10 Zooq credits. There is no contradiction with the annotations.

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

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

The description is two short sentences with the core resource front-loaded. The cost warning is neatly parenthesized, and there is no redundant or filler content.

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

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

With a full output schema, thoroughly described parameters, and safety annotations, the description is complete enough for an agent to select and invoke the tool correctly. The threaded and cost behaviors are disclosed, and the only small gap—explicit sibling routing—is largely mitigated by the schema guidance.

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

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

Schema description coverage is 100%, and the entityId property already explains accepted formats and provenance. The tool description itself adds no additional parameter-level meaning, so the baseline for high schema coverage applies.

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

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

The description clearly identifies the resource as 'Threaded comments/replies on a post' and the title 'List post comments' supplies the verb. It is clear enough for an agent to infer this retrieves comments for a specific post, but it does not explicitly contrast with the sibling comments_all.

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 entityId parameter description provides useful workflow context: get the activity id from companies_posts and note that person feeds are currently unavailable. The single-post framing implies when to use the tool, though it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already mark the operation as read-only and idempotent; the description adds value by disclosing the 10-credit cost and noting the data.post return path. There is no contradiction with 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 compact and front-loaded: purpose first, then the routing rule, then the cost. Every clause earns its place with no filler or repetition.

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

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

For a one-parameter, read-only tool with a rich schema and an output schema, this description covers the essential calling context: single-post scope, return path, comments alternative, and credit cost. Nothing critical is missing.

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

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

The single parameter entityId is fully documented in the schema, including accepted formats and how to obtain it from companies_posts. Since schema coverage is 100%, the description need not add parameter detail; it adds none.

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 that the tool returns the full content of one post and specifies the response location (data.post), which is specific and actionable. It also distinguishes itself from the comments tool by explicitly routing comment requests to /posts/comments.

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

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

It provides a clear when-not/alternative rule: use /posts/comments for comments. It also scopes the call to a single post, so an agent knows this is not for listing or bulk retrieval.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered structurally. The description adds valuable non-obvious behavior by warning that the call 'Costs 10 Zooq credits,' which annotations do not convey. No contradiction with annotations.

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

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

The description is a single tight sentence that delivers the core behavior and the cost caveat with zero filler. It is front-loaded and every part earns its place.

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

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

Combining the description, annotations, and fully documented schema parameters, an agent has everything needed to invoke this read-only reactions list correctly: entity source, accepted id formats, pagination constraint, output shape via schema, and cost. There is no material missing context for this tool's complexity.

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

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

Schema description coverage is 100% and the parameter descriptions are already detailed (entityId accepts bare or urn:li:activity forms; start must be a multiple of 10). The description adds no parameter-level meaning beyond the schema, so the baseline 3 is appropriate.

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

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

The description names the exact output ('People who reacted to a post + reaction type and total') and the annotation title adds the 'List' verb, making the operation clear. It is distinguishable from comment-focused siblings like posts_comments and comments_all because it focuses on reactions rather than comments.

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

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

The description itself does not name alternative tools, but the schema's entityId description provides strong operational guidance: get the id from companies_posts and use data.activities[].entityId, while noting person feeds are unavailable. The credit-cost warning also signals an important consideration before invoking the tool.

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

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

Annotations already cover read-only/idempotent/open-world safety, and the description adds meaningful behavioral detail beyond them: the result is LIVE, concurrent roles are preserved rather than flattened, handle resolution costs no extra credits, not-found profiles are free upstream, and the call costs 10 Zooq credits. No contradiction exists between the description and 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 dense but every sentence carries useful information: result contents, sibling differentiation/usage criteria, parameter guidance, and cost. The first sentence is a long enumeration and the cost detail is buried at the end, preventing a perfect structure score.

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 output schema exists, return values need no deep explanation, and the description already summarizes the key result fields. It covers freshness, sibling routing, parameter choice, cost, and not-found behavior — nothing needed for correct selection or invocation appears missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The schema already documents handle/entityId formats, auto-resolution, accepted aliases, and the OR relationship. The description restates this guidance rather than adding semantically new parameter 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 names a specific resource ('LIVE work history for one person') and enumerates the exact content returned: per-role organization, title, description, location, parsed dates, skills, and concurrent-role groupings. It also distinguishes itself from profile_full_experience by contrasting live data freshness against dataset-record reads. This is a precise, differentiated definition.

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

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

It states when to use this tool ('when you need freshness, per-role skills, or correct handling of concurrent roles') and explicitly names the overlapping alternative (profile_full_experience) and why to avoid it there. It also gives parameter usage guidance (handle vs entityId), including that handle resolution has no extra credit cost and entityId skips the lookup.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds meaningful context beyond those: it returns live-only flags, emphasizes this is a LIVE snapshot rather than the deduplicated record, and discloses a concrete cost of 10 Zooq credits. No contradiction with annotations.

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

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

Three sentences, each earning its place: purpose and distinction, return payload highlights, and cost. The most decision-relevant information is front-loaded in the first sentence.

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

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

For a two-parameter, read-only tool with a rich output schema, the description covers purpose, scope, exclusions, downstream usage, key return value, and cost. It is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, and the schema already explains that handle OR entityId can be provided and that entityId wins when both are present. The description only reiterates 'by handle or entityId' without adding parameter-level detail, so the baseline of 3 is appropriate.

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

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

States a specific verb ('snapshot'), resource ('one profile'), and input mechanism ('by handle or entityId'), and immediately distinguishes itself from the deduplicated records returned by other profile/* endpoints. Also lists live-only flags and the key output entityId, which differentiates it from siblings like profile_full or profile_entity_id.

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

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

Explicitly says this is NOT the deduplicated dataset record other profile/* endpoints return, giving a clear when-not signal. It also explains that the returned entityId is required by every other live person endpoint, implying this tool is the right entry point when you need live data or a downstream entityId.

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 convey read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond annotations by disclosing the 10-credit cost and the live nature of the resolved id, which helps an agent use the tool cost-effectively.

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

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

Two short sentences convey purpose, scope, caching guidance, and cost with zero redundancy. The key outcome is front-loaded and every clause earns its place.

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

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

For a single-parameter lookup with a rich schema, supportive annotations, and an output schema, the description is complete. It states what the tool does, how to use the result, and the operational cost, leaving no critical gap for an agent to call it correctly.

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

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

The input schema is fully covered at 100%, and the schema already explains what 'handle' means, including the URL variant. The description does not add meaning beyond the schema, so a baseline 3 is appropriate.

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

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

The description uses a specific verb ('Resolve') and states the exact resource ('public handle') and output ('person entityId') with the endpoints that consume it. It clearly distinguishes this from sibling lookups like companies_entity_id by specifying the live person endpoints.

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

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

The description gives clear context: this is a prerequisite for live person endpoints and the id should be resolved once and reused. It does not explicitly name alternative lookups or state when not to use it, but the intended workflow is strongly implied.

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, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds meaningful beyond-annotation context: the 10 Zooq credit cost, the alias-equivalence behavior, and the comprehensive scope of the returned record.

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

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

Three dense sentences with no filler: purpose and contents are front-loaded, alias relationships are stated compactly, and the credit cost is isolated at the end. Every sentence earns its place.

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

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

With a present output schema, fully documented parameters, safety annotations, and the credit-cost warning, the description covers everything an agent needs to invoke this read-only canonical profile tool correctly. No critical operational detail is missing.

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

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

Schema description coverage is 100%, and both parameters are well-documented with the 'Provide handle OR id' constraint baked into the schema. The prose description does not add parameter-level semantics beyond that, so the baseline of 3 for high-coverage schemas is appropriate.

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

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

Description opens with a specific verb and resource: 'Complete profile in one call' followed by an enumerated field list. It then establishes this as 'the canonical profile read' and explicitly contrasts with aliases, so an agent can distinguish it from sibling profile tools.

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 names the profile/* alternatives (overview, details, about, education, skills, certifications, full-experience, social-matrix) and states they return the exact same record, telling an agent when this canonical tool is the right choice and that alternatives add no distinct value.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds a meaningful operational detail — the cost of 10 Zooq credits — which is not present in annotations and helps the agent weigh invocation cost. No contradiction with annotations exists.

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 one concise sentence plus a parenthetical cost note. It front-loads the core function and introduces no redundant or tangential information. Every element earns its place.

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

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

For a read-only list operation with rich annotations, a detailed input schema, and an existing output schema, the description is complete. It covers the semantic core and the cost side effect, while parameters and return structure are handled elsewhere. Nothing an agent needs to call it correctly is missing.

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

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

Both parameters are fully documented in the input schema with detailed descriptions of accepted formats (handle, entityId, resolution rules, and the OR condition). The description itself adds no parameter-specific information, which is acceptable because schema coverage is 100% and there is no gap for the description to compensate.

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

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

The description clearly states the resource ('entities the person follows') and enumerates the entity types (companies, groups, people, newsletters), which distinguishes it from sibling tools like profile_full and profile_recommendations. It lacks an explicit verb such as 'get' or 'list', but the intent is unambiguous given the tool name and 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 does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or conditions. However, the phrase 'Entities the person follows' implies a clear use case: when you need the list of followed entities. This is adequate but relies on the agent to infer applicability.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, so the description does not need to repeat those. The description adds meaningful context beyond annotations by warning of the 10-Zooq-credit cost and clarifying the returned content ('author details and text'). This is useful behavioral information, though it stops short of describing any limits, pagination, or failure behavior.

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

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

The description is short and front-loaded, stating the core purpose first and the credit cost in a parenthetical second. Every word earns its place, and there is no redundant restating of the schema. It could be slightly improved by leading with a verb like 'Get' or 'Returns', but it is otherwise efficiently written.

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 low-complexity tool with no required parameters, a detailed input schema, and a present output schema, the description provides the essential context: who the data is about and what it costs. The credit cost is an important operational detail that is not in the schema or annotations. It does not explain when to use the tool versus siblings, but that gap is already reflected in the usage_guidelines score.

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

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

Schema description coverage is 100%, with handle and entityId both documented in detail including format, resolution to entityId, and accepted variants. The tool description adds no parameter-specific semantics beyond reinforcing that the recommendations belong to 'the person'. With full schema coverage, the baseline score of 3 is appropriate.

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

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

The description names the resource ('recommendations'), the subject ('the person'), and the expected content ('author details and text'), so an agent can tell what data to expect. It lacks an explicit verb such as 'get' or 'returns', though the annotation title 'Get profile recommendations' reinforces the intent. Among the profile_* siblings, none is specifically dedicated to recommendations, so the tool is reasonably distinguishable.

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

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

The description implies the tool is used when recommendations for a person are needed, but it never explicitly states when to prefer it over related profile tools like profile_enrich, profile_full, or profile_interests. No alternatives, exclusions, or preconditions are mentioned. Because the name and description make the basic use case inferable, this is adequate but not explicit guidance.

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

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

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint. The description adds value beyond those by disclosing the 10-Zooq-credit cost and emphasizing that the operation starts from one example profile. It does not contradict any annotation.

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

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

The description is compact and front-loaded: it states the core purpose immediately, then adds the cost note in a parenthetical. Every piece earns its place with no redundancy or filler.

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

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

With only two parameters, fully detailed schema descriptions, a present output schema, and strong annotations, the description does not need to explain return values or input formats. It covers the one extra decision-relevant fact, the credit cost, making it complete for selection and invocation.

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

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

Schema description coverage is 100% and the schema already explains handle vs. entityId, automatic translation, and the OR requirement in rich detail. The tool description itself adds no parameter-level meaning, so the baseline 3 is appropriate.

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

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

The description names a specific action ('expand a shortlist') and resource ('professional profiles') and scopes the input to 'one example'. 'Professional profiles' also differentiates this from sibling similar-tools like companies_similar and jobs_similar, so an agent can tell what it does without opening the schema.

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

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

The use case is clear: when you have one example profile and want to build out a shortlist of similar professional profiles. It does not name alternatives or exclusion conditions, so it stops short of a 5, but the context is explicit rather than merely implied.

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 convey read-only/idempotent/non-destructive behavior. The description adds useful behavioral context beyond annotations: results are page-paginated, each call costs 10 Zooq credits, and records are professional plus education-linked. No contradiction with annotations.

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

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

Three short sentences, each carrying useful information: data scope, pagination, and use case/cost. It is efficient and front-loaded, though the phrase 'professional records + the education link' is slightly cryptic.

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 search tool with rich schema descriptions, an output schema, and safety annotations, the description adds the missing contextual pieces: pagination behavior, cost, and intended recruiting use. It is complete enough for an agent to invoke correctly, though it could name related tools.

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

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

Schema description coverage is 100%, so the description does not need to repeat parameters. It adds only the generic 'page-paginated' hint, which is already implied by the page/limit parameters; no additional semantic value 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 identifies the target data (alumni and current students of an institution) and the intent (recruiting and warm-intro sourcing), which makes the tool's purpose clear. It does not explicitly say 'search' or name sibling alternatives, so it lacks explicit differentiation from generic people-search tools.

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

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

It provides clear context: use this when sourcing alumni/current students for recruiting or warm intros. It does not state exclusions or point to alternatives such as search_people, so it falls short of full when-to-use/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 already cover the safety profile (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false). The description adds useful non-annotation-specific behavior: cursor pagination and a credit cost of 10, which helps the agent anticipate side effects and usage cost.

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

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

Three short sentences each earn their place: purpose, pagination behavior, and cost. The main action and scope are front-loaded, with no filler or repetition of schema details.

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 a fully documented 13-parameter schema and an output schema, the description supplies the key invocation-level facts: search action, pagination, and credit cost. The main gap is the missing dataset-vs-live distinction relative to search_companies_live, but that is more a tool-selection concern than an invocation gap.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The description only summarizes the parameters as 'name or website with firmographic filters' without adding detail beyond the schema. It does not need to compensate for gaps, and it doesn't.

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

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

The description uses a specific verb ('Search') and resource ('organizations') and names the scope: by name or website with firmographic filters. It does not explicitly differentiate from closely related siblings like search_companies_live, so it misses the final distinction point for a 5.

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

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

The description provides no when-to-use or when-not-to-use guidance and names no alternatives. Given overlapping siblings such as search_companies_live, companies_name_lookup, and companies_universal_name_to_id, an agent gets no help choosing among search entry points.

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

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

Annotations already mark this as read-only, non-destructive, and open-world. The description adds valuable behavioral context beyond those: offset pagination, the 10 Zooq credit cost, and the not-found-free-upstream behavior. No contradictions with annotations.

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

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

The description is compact and front-loaded. The first sentence establishes what the tool is, the second explains why it exists, and the remaining sentences cover routing, pagination, not-found behavior, and cost. Every sentence earns its place with no filler.

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

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

Given the rich output schema and annotations, the description covers all essential contextual needs: unique differentiators, sibling routing, pagination, cost, and not-found behavior. Nothing an agent needs to decide whether to call this tool is missing.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds meaning beyond the schema by highlighting hasJobs as the unique differentiator and framing headcountRange as a bucketed search dimension, which helps an agent prioritize parameters.

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

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

The description states a specific verb and resource ('LIVE company search') and immediately identifies the tool's unique value: the hasJobs filter 'available nowhere else in the catalog' plus bucketed headcount search. It also explicitly names the sibling alternative (search_companies), making the tool easy to distinguish.

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

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

Usage guidance is explicit: it positions this tool as the one to use for hasJobs and headcount-bucket search, and directly routes firmographic filtering to search_companies instead. This covers when to use, when not to use, and names the alternative.

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

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

Annotations already establish read-only, open-world, idempotent, and non-destructive behavior. The description adds value by disclosing that results are page-paginated and that the tool costs 10 Zooq credits, which are useful operational details not present in the annotations.

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

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

Three concise sentences deliver the core subject, pagination behavior, intended use case, and cost. Every sentence earns its place, with no filler or redundancy.

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

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

For an open-world, read-only search tool with an output schema and fully documented optional parameters, the description covers the essentials: what events are included, how results are paginated, when to use it, and the cost. Nothing an agent needs to decide whether to invoke it is missing.

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

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

Parameter schema coverage is 100%, so the schema already documents all eight parameters. The description contributes contextual meaning by enumerating the event types and noting pagination, but it does not add meaningful details about parameter values or constraints 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 identifies the resource as recent professional job-change events and specifies the three event categories (joined, left, changed titles). It distinguishes this from generic people/job search siblings by focusing on organizational employment events, so an agent can understand exactly what the tool returns.

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

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

The description explicitly states the intended use case: 'trigger-based prospecting and territory monitoring.' It gives clear context for when this tool is appropriate, though it does not name alternatives or state when not to use it, so it stops one point short of the highest level.

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

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

Beyond the readOnly/idempotent annotations, the description discloses exact-match location behavior, the fact that results may differ from LinkedIn's own UI, offset pagination, a 10-credit cost, and that some accepted id filters are not yet usable. This is rich, non-obvious 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 dense but compact. Six sentences cover purpose, location handling, unusable filters, pagination, downstream id usage, and cost, with the core purpose stated first and no filler.

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

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

For a 20-parameter search tool with an output schema, the description covers the remaining decision-critical context: pagination, exact-match limitations, unusable parameters, downstream consumers of the returned jobs, and credit cost. Nothing essential is missing for correct selection and 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%, but the prose adds important cross-parameter meaning: it flags id-typed filters that are not yet usable, explains how to find LinkedIn geo ids, and warns that titles must be ids rather than free text. These caveats are not fully present in every individual parameter 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 opening phrase "Job/opportunity search with the full filter set" clearly identifies both the operation and the resource. The description also connects the returned data.jobs[].id to downstream job endpoints, distinguishing it from detail tools and other search tools in the sibling list.

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

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

The description gives actionable usage guidance: which filters work, which are not yet usable, and how the returned ids feed /jobs/details-v2 and related endpoints. It does not explicitly name alternative search tools for when not to use this one, but the downstream-consumer note strongly implies its role.

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, idempotentHint, and destructiveHint false, covering safety. The description adds genuinely useful behavioral context beyond annotations: cursor-based pagination and a 10-Zooq-credit cost, which are not visible in the schema or 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 one tight, front-loaded clause followed by a brief pagination note and a cost parenthetical. Every phrase earns its place and there is no redundant restatement of the tool name or schema.

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

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

The description gives a solid high-level overview, and the rich annotations plus output schema cover safety and return structure. However, the tool has 33 optional parameters and a closely related sibling search_people_live; the description does not clarify the dataset-vs-live distinction or provide selection guidance, leaving an important gap for an agent choosing between siblings.

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

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

Schema description coverage is 100%, so the schema already documents all 33 parameters. The description adds a useful high-level list of filter categories, but it does not add parameter-specific meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and object — 'Search professional records' — and enumerates the main filter dimensions (name, title, company, skills, education, tenure, geography). However, it does not explicitly differentiate this tool from sibling search_people_live or search_alumni, so the agent must infer which variant this is.

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

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

The description gives no guidance on when to use this tool versus alternatives. It does not mention search_people_live, search_alumni, or any exclusion criteria, leaving the agent without decision support for choosing among the search-family siblings.

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

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

Annotations already establish read-only, non-destructive, idempotent behavior. The description adds genuinely useful behavioral context beyond that: it is LIVE data, offset-paginated, has no charge for not-found results, and costs 10 credits per call. No contradiction exists.

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, front-loads the core differentiator, and each sentence contributes either differentiation, usage guidance, or operational detail. There is no filler or redundancy.

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

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

Given rich annotations, full parameter descriptions, and an output schema, the description supplies the remaining operational context an agent needs: pagination style, cost, not-found behavior, and how this tool complements search_people. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The tool description itself does not add parameter-level detail, but the schema already carries comprehensive guidance, including caveats about id namespaces and free-text limitations.

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

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

Names a specific verb and resource ('LIVE people search') and immediately states its unique capability: filtering by current company, past company, and school together. It also distinguishes itself from search_people, making it clearly identifiable among the sibling tools without opening schemas.

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

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

Explicitly tells the agent when to choose this tool over the main alternative: 'use this one for company-history sourcing, that one for broad firmographic filtering.' The contrast in pagination style (offset-paginated vs. cursor-paginated) and geo handling further clarifies selection.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds useful behavioral context: partial-match search, pagination behavior, and a 10-credit cost. This meaningfully supplements the annotation-only safety profile.

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

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

Three short sentences, each adding distinct information: what it searches, how results are paged, what to use it for, and cost. No filler or repetition of schema details.

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

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

For a simple search tool with fully documented parameters, rich annotations, and an output schema, the description covers what an agent needs: query behavior, pagination, intended use, and cost. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying that name performs a partial match and that results are page-paginated, which is not fully evident from the parameter names alone.

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

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

States a clear action and resource: search institutions by name with partial matching. It also names the intended outcome, discovering an institution's inst_id or normalized_name, which separates it from people, company, job, and post search tools.

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 context for when to use the tool: to discover an institution's inst_id or normalized_name. It does not explicitly name sibling alternatives or when not to use it, but the use case is clear enough for an agent to select it appropriately.

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