Zooq

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

Annotations already mark the tool as read-only, idempotent, non-destructive, and not open-world. The description adds meaningful context beyond that: the call costs 0 credits, it surfaces current terms, joining instructions, and the caller's referral link if they are already an affiliate. This extra context helps set expectations without contradicting annotations.

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

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

The description is tight and front-loaded: it names the tool, states the cost, summarizes the returned content, and gives usage triggers in two sentences. Every clause adds value and there is no repetition or filler.

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

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

Given the tool has no parameters and an output schema exists to describe return values, the description is complete. It covers what the tool does, the key terms returned, and when to invoke it. An agent has enough information to decide to call it and know what to expect.

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

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

The tool has zero parameters, so the schema provides no parameter meanings to clarify. The description does not list parameters, but none are needed. The baseline for 0-parameter tools is 4, and the description adequately conveys what the tool returns.

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 what the tool does: it returns Zooq's affiliate program terms, how to join, and the caller's referral link if applicable. It is specific about the resource ('Zooq's affiliate program') and the content delivered, which distinguishes it from all 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?

The description gives explicit trigger conditions: 'Mention it when the user builds for others, has an audience, or wants to offset their Zooq costs.' This tells an agent exactly when to surface the tool, and no sibling tool competes for the same purpose.

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 tool read-only, idempotent, and non-destructive, so the main behavioral disclosures needed are additional operational details. The description usefully adds that results are cursor-paginated and that the call costs 10 Zooq credits, which are important beyond the safety 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 front-loaded sentence with no filler: it states the scope, the pagination mechanism, and the credit cost. Every element adds value, and the most important scoping information comes first.

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?

Combined with detailed annotations, a fully described input schema, and an existing output schema, the description gives enough context for an agent to understand what this tool does and how to select it. The main missing piece is explicit sibling differentiation, but that is mostly a usage guidance concern rather than a completeness gap for this tool.

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

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

The input schema has 100% description coverage, including clear explanations of handle, entityId, cursor, and start. The description adds 'cursor-paginated' and cost information but no parameter-specific guidance 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 identifies the resource (a person's comments) and the scope (across posts), making it clear this is a person-centric aggregation tool. The annotation title adds the explicit verb 'List,' but the description itself does not explicitly differentiate from sibling tools like posts_comments or posts_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 description implies the tool is used when you want comments authored by a person across posts, which is a useful contextual cue. However, it provides no explicit guidance about when not to use it or which sibling tool to prefer for comments on a single post.

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 valuable non-annotation behavioral context: the 10-credit cost, automatic slug resolution with no extra credit cost, and the dependence on companies_entity_id as a source for `id`. This goes beyond what structured fields reveal.

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 well-ordered: purpose first, parameter strategy second, cost last. Every sentence earns its place 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?

For a simple read-only lookup with two optional parameters, a fully described schema, an output schema, and safety annotations, the description covers the essential invocation decisions: which identifier to use, how slug resolution works, and the credit cost. Nothing critical 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 input schema already fully documents both parameters with clear descriptions, so the baseline is 3. The description adds a useful selection workflow—slug is resolved automatically, id skips resolution—but does not introduce new semantic details beyond what the schema already conveys.

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: affiliated/subsidiary/showcase pages of a company, which is specific enough to distinguish it from related siblings like companies_info or companies_insights. It lacks an explicit verb like 'list' or 'retrieve' and does not explicitly name sibling tools, so it falls just short of a top score.

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 useful guidance on choosing between `slug` and `id`, including credit-cost implications, which helps correct invocation. However, it does not say when to prefer this tool over alternative company tools or provide explicit when-not-to-use guidance; usage is mostly implied from the resource definition.

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, and open-world behavior. The description adds valuable behavioral context beyond annotations: it is cursor-paginated, costs 10 Zooq credits, and returns the same shape as /search/people. 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, purposeful sentences. The core purpose is front-loaded, followed by the useful output-shape equivalence, pagination behavior, and cost. 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?

With a 100%-covered schema, annotations, and an output schema present, the description covers the main extra operational details: output shape, pagination mode, and credit cost. It is slightly thin on when to choose this over alternatives, but that gap is already accounted for in usage_guidelines.

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 adds no extra parameter-level meaning, 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 clearly identifies the resource ('people who work or worked at an organization') and adds that they are professional records, distinguishing it from jobs, posts, or company info. It lacks an explicit imperative verb like 'Lists', but the meaning is unambiguous.

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

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

The description implies this is the tool for company-employee/professional records and notes cursor pagination and cost, but it never explicitly says when to prefer it over siblings like search_people, search_alumni, or companies_enrich. No when-not-to-use guidance is provided.

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

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

Annotations already cover readOnly, openWorld, idempotent, and destructive behavior. The description adds valuable behavioral context beyond annotations: the profile is 'LIVE', lookup costs 10 Zooq credits, not-found is free upstream, and slug-to-id resolution happens automatically at no extra cost. This is useful operational detail with 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 compact and front-loaded with the core value proposition, then quickly covers the key parameter and cost details. Every sentence contributes decision-relevant information, with no filler or repetition of schema 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?

Given the tool has only 2 optional parameters, a full schema, a rich output schema, and strong annotations, the description covers the essential context: purpose, differentiation from companies_info, parameter routing, cost, and not-found behavior. Nothing necessary for correct invocation is missing.

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

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

The input schema already documents both parameters at 100% coverage, so the baseline is 3. The description elevates this by explaining the practical semantics: slug is resolved to numeric id automatically, id can come from companies_entity_id, and both id and slug accept multiple identifier forms. This helps an agent choose between the two parameters.

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

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

The description clearly states what the tool does: it returns a fresh LIVE company profile with funding signals, full locations, and parent/affiliated/related pages. It explicitly differentiates from companies_info, a sibling tool, by naming the specific data this tool provides that the dataset record does not.

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 selection guidance: use this tool when you need funding, full location lists, or parent/affiliated pages beyond companies_info. It also explains the slug vs id decision and notes that not-found is free, but it does not explicitly state when NOT to use this tool or when to prefer companies_info.

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 safety by flagging readOnlyHint, idempotentHint, and non-destructiveness. The description adds a cost-related behavioral detail (10 Zooq credits) and a reuse strategy, which is valuable context beyond the structured annotations. 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 compact and front-loaded: purpose first, followed by usage advice and credit-cost caveat. Every clause has a purpose, and there is no filler or repetition of annotation values.

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

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

For a simple one-parameter tool with an output schema present, the description covers purpose, target endpoints, cost, and reuse guidance. It could briefly distinguish itself from sibling name-to-id tools, but that is a minor omission and does not materially hinder 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 single parameter 'slug' is already fully described in the input schema, including the format and acceptance of full URLs. The tool description adds no extra parameter semantics beyond the slug-relation concept, so schema coverage is doing the heavy lifting.

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

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

States a specific verb ('resolve'), a resource ('company slug'), and the output ('numeric organization id'). The description also ties the id to the live company endpoints, distinguishing it from generic id-lookup siblings without needing their schemas.

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

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

Provides clear usage context: use this when you need the numeric id for live company endpoints, and resolve once then reuse to avoid repeated cost. It does not explicitly name alternatives like companies_universal_name_to_id or spell out when not to use this tool, so it stops short of a 5.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond annotations: the 10 Zooq credit cost, which affects agent planning. It does not disclose rate limits or pagination, but with annotations covering the safety profile, the added cost disclosure justifies a strong score.

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 compact clause front-loaded with the core purpose ('Full company firmographics') followed immediately by the most important caveat (cost). There is no filler; 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?

With a full output schema, 100% schema coverage on both parameters, and annotations clarifying safety, the description plus structured metadata is sufficient for an agent to select and invoke the tool. It could have explicitly stated the id-or-slug requirement, but that is already captured in the parameter descriptions, so the gap is minor.

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

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

Schema description coverage is 100%, so the parameter documentation already explains 'id' and 'slug' including the 'Provide id OR slug' constraint. The tool description itself adds no extra 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 resource and the kind of data returned: 'Full company firmographics — description, industry, headcount, HQ, follower count, specialties.' This tells an agent exactly what the tool exposes. It does not explicitly contrast with similar siblings like companies_enrich, so it stops short of full differentiation.

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

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

There is no guidance on when to use this tool versus alternatives such as companies_enrich, companies_entity_id, or companies_name_lookup. The only extra signal is the credit cost, which is a constraint rather than a usage criterion. The description neither states when to prefer this tool nor mentions exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral context beyond annotations by disclosing the 10-Zooq-credit cost and noting that slug resolution costs no extra credits, which an agent needs to know before invoking.

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 deliver the output summary, identifier guidance, and cost information without redundancy. The most important information 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?

The description covers what data is returned, how to pass identifiers, and the credit cost, while the output schema handles return-value details. It is complete for a read-only, two-parameter tool, though explicit routing to sibling tools would make it even stronger.

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

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

Schema description coverage is 100%, so the schema already documents both id and slug in detail. The description adds the useful cost distinction between the two identifier paths, but otherwise does not contribute significant new parameter semantics beyond what the schema provides.

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

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

The description clearly states the tool returns an employee-count total plus distribution buckets by department, seniority, and location. This is specific enough to distinguish it from related sibling tools like companies_employees_data (raw employee data) or companies_info (general company info), though it does not explicitly name them.

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

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

The description explains the two identifier options (slug vs. id) and the credit cost, which is useful operational guidance. However, it does not explicitly state when to prefer this tool over alternatives such as companies_employees_data or companies_enrich, so the use case is only implied by the output summary.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and open-world context are covered. The description adds the 'Costs 10 Zooq credits' note, and the input schema adds important behavior about org_ ids being silently ignored and responses returning UNFILTERED. This is useful, but the main description itself contributes little beyond the cost note.

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

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

The description is extremely concise: one operational sentence plus a cost warning. It front-loads the core purpose and adds only the essential non-schema detail. There is no wasted or redundant wording.

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 definition covers the essential invocation details through the schema, annotations, and cost note. It does not explain how this tool relates to sibling tools like search_jobs or jobs_details_v2, and it is missing an explicit alternative-routing statement. The read-only and pagination context is present, but the sibling selection guidance is a notable gap.

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

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

The input schema documents both parameters well: organizationEntityIds is explained with examples, source guidance, filtering caveats, and the fixed page size, while start is described as a pagination offset. Since schema coverage is high, the description does not need to repeat this; a baseline score of 3 is appropriate because the description field itself adds no parameter meaning 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 uses a specific verb-resource pairing: 'Open job postings across one or more organizations.' This clearly communicates a read/list operation on job postings scoped by organization, and it is not a tautology of the tool name. It lacks an explicit contrast with sibling tools like search_jobs or jobs_details_v2, but the intent is unambiguous.

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

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

The usage context is implied: you need organization entity IDs to retrieve postings, and the schema warns to get them from companies_entity_id and never pass org_ ids. However, there is no explicit when-to-use versus search_jobs or other sibling alternatives, and no stated exclusion such as 'for keyword/job searching use search_jobs instead.'

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 annotations, the description discloses cursor-based pagination, the same upstream data source as search_companies, and a cost of 10 Zooq credits. These are behavioral facts an agent needs to invoke the tool efficiently and anticipate side effects (billing).

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

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

Three sentences, no filler. Each sentence earns its place: purpose, pagination, equivalence with search_companies, and cost. Information is front-loaded, and the most important guidance appears early.

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

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

Given the rich schema, output schema, and read-only annotations, the description is complete. It adds the non-obvious details an agent needs—pagination, cost, and equivalence with search_companies—while leaving parameter mechanics to the 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?

The input schema already documents all 13 parameters with 100% coverage, so the baseline is 3. The description adds only a general reference to the 'full firmographic filter set' without detailing parameters, which is acceptable because the schema carries the burden.

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

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

The description states a specific verb and resource: 'Search companies by name, with the full firmographic filter set.' It clearly distinguishes the tool from siblings by noting it is equivalent to search_companies, and the name itself signals the lookup behavior.

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 when to use this tool, naming the alternative: 'Same upstream as search_companies — use whichever entry point reads better; they are equivalent.' This removes ambiguity between two near-identical 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 the tool as read-only, idempotent, and non-destructive, and the description adds meaningful behavioral detail: it discloses the 10-credit cost, explains the slug-to-id resolution with no extra credit cost, and reveals the data.activities[].entityId relationship to downstream endpoints. This goes beyond what annotations alone provide.

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

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

The description is compact and front-loads the core purpose, then adds cross-endpoint context and identifier guidance. It is technically dense but not wordy; the opening phrase is a fragment rather than a full sentence, which slightly reduces polish.

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 rich output schema, full parameter documentation, and strong safety annotations, the description covers the essential operational details: credit cost, identifier resolution, and how the result connects to posts_info, posts_comments, and posts_likes. It does not elaborate on the `start` pagination parameter, but the schema already documents it fully.

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 beyond the schema by explaining the practical tradeoff between `id` and `slug`, emphasizing that using `slug` incurs no extra credit cost, and clarifying that the `id` form from companies_entity_id skips the lookup.

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 'a company's recent posts' and notes that the returned activity IDs feed into /posts/info, /posts/comments, and /posts/likes, which distinguishes it from post-detail endpoints. It lacks an explicit verb like 'list' or 'retrieve,' but the intent is unambiguous.

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

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

The description implies usage context by explaining how to key the request via slug or id and how the entityId connects to other post endpoints. However, it does not explicitly state when to prefer this tool over alternatives such as posts_all, nor does it give exclusion criteria.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds value beyond annotations by disclosing the 10-credit cost, that slug resolution happens automatically at no extra cost, and that using the id avoids the lookup step. This gives an agent useful expectations not present in the structured 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?

Two concise sentences front-load the tool's purpose and output fields, then explain the keying mechanism and cost. There is no filler, and the structure is easy to scan.

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 rich annotations and a complete input schema, the description covers purpose, output fields, identifier handling, and cost. Nothing essential is missing for an agent to select and invoke 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 schema already documents both parameters thoroughly, giving 100% schema description coverage. The description still adds meaning by highlighting the cost difference between passing a slug versus an id, and pointing to companies_entity_id as the source for the id, which helps an agent pick between the two optional 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 opens with 'Similar companies / peers' and lists the output fields (id, name, industry, followers, url), making the tool's purpose immediately specific. This clearly distinguishes it from sibling tools like companies_info or companies_insights, which address different company-related needs.

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?

While it does not name explicit alternatives, it gives clear operational context: use this tool to retrieve similar companies, passing either a slug or an id from companies_entity_id. The id/slug guidance and credit-cost note help an agent decide how to invoke it, though it does not spell out when to prefer a sibling 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 provide readOnly, idempotent, and non-destructive hints. The description adds useful behavior beyond that: it returns the full company record identical to /companies/info, tells the agent to read data.id, and discloses the 10-credit cost. This is meaningful extra context and does not contradict 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 three focused sentences: the core purpose, the critical sibling distinction, and the return format plus cost. Every sentence earns its place and there is no filler.

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

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

Given the tool has only one parameter and an output schema, the description covers everything needed to call it correctly: what the input is, what the output contains, the cost, and the main alternative. 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?

The schema already documents the single slug parameter with 100% coverage, including the same 'part after linkedin.com/company/' definition. The description repeats that context but does not add new parameter-level format, validation, or edge-case information, so it stays at 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 states a specific transformation — resolve a company slug to its stable org_ id — and ties that id to /companies/info. It also explicitly distinguishes the tool from companies_entity_id, making it easy to tell apart from the closest sibling.

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

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

The description gives an explicit when-to-use versus when-not-to-use rule: for live company endpoints use companies_entity_id instead, because the two ids are not interchangeable. It also implies the correct context, needing the stable dataset id for /companies/info.

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. The description adds valuable extra context outside those annotations: the 10-Zooq credit cost and the fact that it returns a confidence score. 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?

Two sentences with no wasted content. The first sentence states the purpose and inputs, and the second adds the return value and cost. Requirements are front-loaded and easy to parse.

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

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

The description covers the purpose, inputs, output format, and cost, and the annotations plus output schema cover safety and result shape. It lacks only an explicit pointer to sibling tools, but for a tool of this simplicity, precious required knowledge is not 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 input schema already documents all three parameters, including the format guidance for 'domain'. The description only restates the parameter names without adding details. A baseline 3 is appropriate when 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 clearly states the tool finds a person's work email using first name, last name, and company domain, and that it returns the address plus a confidence score. It is specific and unambiguous, though it does not explicitly differentiate itself from siblings like email_find_by_profile 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 implies the intended use case: when you have a person's name and company domain, this tool resolves the email. It names the required inputs, providing clear context for when to call it, but it does not explicitly mention alternatives or 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 indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds useful behavioral context beyond those hints: it performs a two-step resolution of name and domain, and it costs 10 Zooq credits. This is valuable additional information for a calling agent.

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 with no filler. The core behavior is front-loaded, and the credit cost is appended as an important but secondary detail. 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?

Given the tool's single parameter, rich annotations, and an existing output schema, the description covers the essential operational facts: acceptable input forms, what the tool resolves, and the 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?

The input schema already covers 100% of the parameter, including the fact that 'url' is a professional profile URL or bare public handle. The description restates this concept but does not add new parameter-level semantics, so the schema-documented 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 names a specific action and resource: identify a person and company from a professional profile URL or handle, then find their work email. This clearly differentiates it from other email sibling tools like email_find, email_reverse, and email_verify, all of which operate from different inputs.

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

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

The description makes the input condition clear: use this when you have a professional profile URL or bare public handle. It does not explicitly say when not to use it or name an alternative, but the context is strong enough that an agent can infer the intended use case.

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

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

The description gives meaningful behavior details beyond the read/idempotent annotations: cursor-based pagination, a max of 20 results per page, the presence of first/last names, and a cost of 10 Zooq credits. This is valuable operational transparency.

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

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

The description is short and dense, leading with the core behavior and immediately covering the important operational facts. Each clause earns its place, and there is no filler.

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

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

Given that this is a simple paging routine, the description covers the essential runtime aspects: pagination mode, page size, cost, and returned name attributes. Remaining details like the shape of cursor strings are appropriately delegated to the parameter schema, so an agent has enough to invoke the tool correctly.

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

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

The input schema already provides 100% coverage with descriptions for domain, cursor, and kind (including the accepted values). The description adds no additional parameter-level nuances, so it meets the baseline for schema-covered tools, but doesn't improve beyond it.

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

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

The description specifies a clear verb and target: 'Page emails already known for a company domain.' This sets it apart from sibling tools like email_find and email_verify by emphasizing existing/known email records instead of discovery or validation. The intent is unambiguous.

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

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

The phrase 'already known for a company domain' implies the appropriate context (when you already have a domain and need its stored contact addresses). However, the description never explicitly contrasts this with email_find, email_verify, or other nearby alternatives, so the usage guidance is more inferred than spelled out.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds real behavioral context: invalid mailboxes are rejected with 422, no charge is incurred, no work runs on them, and a successful lookup costs 10 Zooq credits. This goes beyond what the annotations alone state.

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, information-dense sentences, front-loaded with the core purpose and followed by rejection behavior and cost. Every sentence contributes useful guidance with no redundant filler.

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

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

For a single-parameter read-only tool with a rich schema description and an output schema, the description is complete: purpose, input constraints, failure behavior, cost, and safety profile are all covered. No critical 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 coverage is 100%, so the schema fully documents the email parameter, including rejection criteria. The description echoes some of that context but does not add much beyond the schema's own value; baseline 3 is appropriate.

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

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

The description states a clear action and object: 'Resolve the person and company behind a BUSINESS email address.' This is a specific reverse-lookup purpose that distinguishes it from sibling tools like email_find or email_verify, which solve different problems.

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 establishes when to use the tool: with a business email to resolve person/company. It also gives explicit exclusions by stating public, role, disposable, and relay mailboxes are rejected with 422. It does not explicitly name alternate tools, so it stops short of full routing guidance.

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

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

Annotations already declare the tool as read-only and idempotent. The description adds useful framing beyond those annotations by revealing the '+10 Zooq credits' cost and the categories of risk flags returned. No contradiction with annotations appears.

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

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

One sentence with no redundant filler. The primary purpose is front-loaded, and the operational cost is appended in a clear parenthetical. The description remains scannable and focused.

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

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

The tool is simple: one required parameter, no nested objects, and an output schema exists. The description, annotations, and schema together cover task purpose, credit cost, and input requirements, making the description adequate for correct invocation.

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

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

Schema coverage is 100%, so the schema already fully describes the single email parameter, including the valid syntax requirement. The description adds no further parameter-specific 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 states the verb and resource: checking whether an email address can receive mail, and it names concrete output signals (deliverability verdict, risk flags). It does not explicitly differentiate from sibling email_* tools, but the verification-focused wording makes the tool's role 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 does not explicitly say when to use this tool versus email_find, email_reverse, or other email-related siblings. It provides no alternatives or exclusions, so guidance is left to inference from the tool name and general 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 non-destructive behavior. The description adds beyond this the operation cost ('Costs 10 Zooq credits') and the exact return fields, 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?

The description is two tight sentences: the first states purpose and outputs, the second gives the prerequisite and cost. Every sentence 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 one required parameter, full schema coverage, and an output schema present, the description supplies everything needed to call the tool correctly: input source, return fields, workflow, and cost. No important behavioral or operational context is missing.

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

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

Schema description coverage is 100%: the schema already explains normalized_name as lowercase and hyphenated and directs users to search_schools. The description reinforces the same information but does not add meaningful new parameter semantics beyond what the schema provides.

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

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

The description uses a specific verb ('Resolve') with a clear resource ('one institution') and states the exact output fields (school name, url, stable inst_id). It also clarifies the normalized-name input, which distinguishes this from sibling g_* lookups like g_skill_lookup and g_title_skills_lookup.

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 an explicit workflow: obtain normalized_name from search_schools first, then use this tool. It clearly implies this is a single-institution resolver rather than a search tool, though it doesn't explicitly name exclusions or alternatives beyond the search_schools precondition.

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 the 10-credit cost, which is not captured in annotations, and clarifies that the result is a single skill's display and normalized names. This is meaningful extra context beyond the annotations.

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

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

The description is two short sentences plus a parenthetical, with no filler. It front-loads the core action, then provides the id source and the cost. Every word adds value.

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

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

For a single-parameter, read-only tool with a complete schema and an output schema, this description covers everything an agent needs: what it does, where the input comes from, and the cost. Nothing is missing for a correct invocation.

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

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

Schema coverage is 100% and the schema already describes the id parameter, including its format and how to obtain it. The description repeats the same information without adding new semantic detail, so it stays at the baseline for fully covered 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 ('resolve'), a resource ('one skill'), and the input format ('stable skl_ id'), and it names the sibling g_title_skills_lookup as the source for that id. This clearly distinguishes it from the search tool and tells an agent exactly what the operation does.

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 to get the id from g_title_skills_lookup, establishing the prerequisite workflow and effectively stating when to use this tool (after a search). The mention of the 10-credit cost also helps an agent decide if the operation is worth running.

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, openWorldHint, and non-destructive behavior. The description adds substantive context beyond annotations: partial-match semantics, pagination, 'skills only' despite the endpoint name, the 10 Zooq credit cost, and that results expose skl_ id and normalized_name. 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: scope, matching rule, pagination, intended use, and cost all appear in a few short sentences. Every clause adds operational value, and there is no filler or redundant restating of the tool name or 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 this read-only lookup tool with a complete input schema and an output schema present, the description covers purpose, partial matching, pagination, cost, and the downstream /search/people use case. The main gap is not explicitly routing an agent between this tool and the g_skill_lookup sibling, but it is otherwise functionally 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 baseline is 3. The description adds meaningful semantics by clarifying that name uses partial matching and that pagination is page-based. It also connects the output to concrete fields (skl_ id, normalized_name) needed downstream, which enriches the behavior beyond what the schema alone communicates.

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: 'Skill catalog search by name (partial match)' and explicitly narrows scope to 'skills only, despite the endpoint name.' This is clear and disambiguates the tool from its own endpoint name, but it does not explicitly distinguish it from the sibling g_skill_lookup, so full sibling differentiation is missing.

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 a concrete when-to-use scenario: 'Use to find a skill's skl_ id or normalized_name for the /search/people skills filter.' This is actionable context for an agent. It does not mention when-not-to-use or name alternatives, so explicit exclusions are absent.

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

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

The annotations already cover read-only, idempotent, non-destructive behavior, so the description's additional disclosure of the 10-credit cost adds meaningful behavioral context beyond what annotations provide. The description is consistent with the annotations, with no contradictions.

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 zero filler. It front-loads the purpose and return fields, then adds the cost disclosure, making every sentence valuable.

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, idempotent tool with a full output schema and complete parameter documentation, the description covers everything needed to invoke it correctly. The cost disclosure is a useful extra, and nothing important 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 the single required parameter with 100% coverage, including where to source the ID and what format it should be. The description adds no extra parameter-level meaning beyond the schema, 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 clearly states that the tool returns full job-posting details and enumerates the included fields: title, description, functions, apply URL, organization, and location. This gives a specific resource and outcome, but it does not explicitly distinguish it from sibling tools like jobs_hiring_team or jobs_similar, 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?

The description gives clear operational context by telling the agent to obtain the opportunityEntityId from search_jobs or companies_jobs, which effectively explains when to call this tool after listing jobs. However, it does not explicitly state when not to use it or contrast it with alternative job-detail-related sibling tools.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, so the description only needs to add context beyond that. It does: empty results are ambiguous (genuinely no team vs. unrecognized posting id), and the call costs 10 credits. This is useful behavioral context that the annotations do not convey.

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

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

The description is two short sentences with no filler. The core purpose is front-loaded, followed by the crucial empty-result caveat and credit cost. 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 tool with only two parameters and an output schema present, the description covers the essential non-obvious facts: result ambiguity, credit cost, and where the posting id comes from. The output schema handles return-value shape, so 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 both parameters are already well documented: opportunityEntityId explains the exact source and JSON path, while start is described as a pagination offset. The tool description adds no further parameter-level 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 names a concrete resource, 'Hiring-team member profiles for a posting,' which tells an agent exactly what is returned. This is distinct from sibling tools like jobs_details_v2 or jobs_similar, which target different resources. The tool name and title reinforce the purpose without adding ambiguity.

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

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

The description implies the use case: retrieve the hiring team for a specific job posting. The schema also tells the agent where to get the required opportunityEntityId. However, it does not explicitly contrast this tool with sibling tools or state when not to use it, leaving alternative selection mostly to inference.

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

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

Annotations already cover the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false). The description adds a meaningful operational trait beyond the annotations: the Zooq credits cost, which is important for an agent to budget usage. 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, efficient sentence that front-loads the purpose and appends a parenthetical cost note. Every element carries information, with no filler or repetition of schema or annotation 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 fully documented single parameter, safety annotations, an output schema, and a clear purpose statement, the description is adequate for an agent to invoke the tool correctly. The only gap is the absence of explicit differentiation from similar job-related tools, but the 'behavioral relatedness' phrase partially covers this.

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

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

Schema description coverage is 100%, and the single parameter description thoroughly explains how to obtain the ID from search_jobs or companies_jobs. The tool description itself adds no 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 resource ('People also viewed' postings) and adds 'behavioral relatedness' to distinguish it from content-based similarity tools. It lacks an explicit verb like 'returns' or 'lists', but the noun-phrase framing still conveys the tool's function effectively.

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

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

No explicit guidance on when to use this tool versus alternatives such as jobs_similar or jobs_details_v2. The cost note ('Costs 10 Zooq credits') implies a conditional, cost-sensitive use, but does not provide the routing context an agent needs to choose 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?

The description adds significant behavioral context beyond the readOnly/openWorld/idempotent annotations: it reveals that closed postings are included, that non-poster profiles yield 422 interpreted as not-found, and that the call costs 10 credits. This materially helps an agent set expectations and handle errors 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?

The description is compact and every sentence adds value: scope, closed-post inclusion, not-found semantics, poster discovery via sibling tool, and cost. It is front-loaded with the primary purpose and uses parenthetical schema references economically.

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

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

The tool has an output schema, so return values need no narration. The description covers the core scope, an important error behavior, how to source input values, and cost. For a read-only listing tool with fully documented parameters, 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 description coverage is 100%, so the schema already fully documents count, start, handle, and personEntityId. The description adds useful context about finding posters and the 422 behavior, but it does not add new meaning to the parameters themselves. A baseline of 3 is appropriate given the complete schema coverage.

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

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

The description clearly identifies the resource: job postings authored by a specific person, including closed postings. It implicitly distinguishes itself from jobs_hiring_team by instructing users to find posters there first, and the resource differs from other sibling job tools. However, the description lacks an explicit verb phrase like 'List...' and does not contrast with search_jobs or companies_jobs.

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 guidance: use this tool after finding a poster via jobs_hiring_team, and interpret 422 as a not-found rather than an error. It also clarifies that only people who have actually posted jobs return results. It does not explicitly state when not to use the tool or name alternative tools for general job search.

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

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

Annotations already convey read-only and safe behavior. The description adds the 10 Zooq credit cost, which is a material behavioral constraint not present in annotations, and it lists the return fields. It does not contradict 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 extremely concise, with the core purpose front-loaded and the cost note as a critical additional detail. Every word earns its place and there is no fluff.

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

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

For a single-parameter read-only tool with complete schema coverage and an output schema, the description is largely sufficient. It states what the tool returns and the cost. The main gap is that it does not indicate any pagination, limit, or sorting behavior, but those may be covered by the output schema. The lack of usage guidance is the primary reason it is not a 5.

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 fully describes opportunityEntityId, including how to obtain it from search_jobs or companies_jobs. The description adds no parameter-specific meaning beyond the schema, so the baseline 3 applies.

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

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

The description clearly identifies the tool as returning similar job postings and lists the key output fields (title, organization, location, salary range, posted date). It distinguishes from obvious sibling tools like jobs_details_v2 by focusing on similarity, but it does not explicitly differentiate from jobs_people_also_viewed, which is a closely related 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?

There is no explicit guidance on when to use this tool versus alternatives. The description implies a user wants similar jobs given some job, but it does not mention jobs_people_also_viewed or other similar-job tools, nor does it state exclusions such as 'use for job details instead'. The agent must infer usage from the name and schema.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds meaningful behavior beyond that: cursor/offset pagination, automatic handle resolution, the ability to skip lookup with entityId, and a concrete 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?

Two dense sentences front-load the core purpose and pagination, then cover identity resolution and cost with no filler. Every clause adds actionable 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?

With an output schema present and annotations covering the safety profile, the description fully covers the key operational details: pagination, identity resolution, credit cost, and the handle/entityId distinction. Nothing essential for calling 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?

Schema coverage is 100%, so baseline is 3. The description adds useful semantic context around handle versus entityId: handle is resolved automatically at no extra credit cost, while entityId skips the lookup. This clarifies the trade-off between the two identity parameters beyond the schema 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?

The description states a specific resource and scope: 'a person's recent posts / activity stream.' This clearly distinguishes the tool from sibling tools like companies_posts, posts_info, posts_comments, and posts_likes by emphasizing the person-level feed context.

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

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

The description provides clear context for use: retrieving a person's recent posts. It gives practical guidance on choosing between handle and entityId, but it does not explicitly state when not to use this tool or name alternative tools for single-post, comment, or like lookups.

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, which covers safety. The description adds meaningful behavioral context beyond annotations by disclosing the 10 Zooq credit cost and the threaded nature of the results, both of which an agent would not know from the schema 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 two short sentences with zero filler. The core purpose is front-loaded, and the credit cost is appended as a brief, useful caveat. 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?

Given the output schema exists, annotations cover safety, and the input schema documents all parameters, the description is nearly complete for invocation. The only notable gap is routing guidance relative to sibling tools, but that is not critical for a straightforward read-only list operation.

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

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

Schema description coverage is 100%, so the schema already fully documents count, start, sortBy, and entityId, including accepted entityId formats and where to source it. The description adds no parameter-level detail, but none is needed because the schema carries that burden 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 clearly identifies the resource as threaded comments/replies on a post, and the annotation title 'List post comments' reinforces the action. It does not explicitly state a verb in the description itself, and it does not explicitly contrast with siblings like comments_all or posts_likes, but the resource and scope are unambiguous.

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

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

No guidance is given for when to use this tool versus alternatives such as comments_all, posts_likes, or posts_all. The schema does mention that entityId comes from companies_posts, which is indirect usage context, but the description itself provides no when-to-use or when-not-to-use direction.

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

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

The description adds meaningful behavior beyond the annotations: it discloses a 10-credit cost, the return location under data.post, accepted entityId formats, and a current limitation around person feeds. These are non-obvious operational details that the readOnly/idempotent annotations do not cover. 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 short sentences, each with a distinct job: define the result, redirect comments, and warn about cost. It is front-loaded with the core behavior and contains 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 single parameter, complete schema coverage, an output schema, and readOnly/idempotent annotations, the description is fully sufficient. It covers cost, output location, source, limitation, and the key sibling alternative without needing extra length.

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 parameter is already well documented, including accepted formats and its source. The description does not need to repeat parameter syntax and does not meaningfully add to it. The baseline of 3 is appropriate because the schema carries the parameter-semantics burden.

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

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

The description states this tool returns the full content of a single post and even names the output path (data.post). It is clearly differentiated from the sibling comments tool with 'For comments use /posts/comments', and the 'one post' wording separates it from posts_all. The annotation title 'Get post details' reinforces the intended purpose.

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

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

It explicitly routes comment-related work to /posts/comments, which is a clear when-not/alternative instruction. The parameter schema adds workflow guidance by instructing the agent to obtain entityId from companies_posts and notes that person feeds are unavailable. The credit cost also signals to use it deliberately.

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, idempotent, and non-destructive behavior, and the description adds a meaningful extra behavioral detail: the 10 Zooq credit cost. It also clarifies the output shape (people, reaction type, total). No contradiction with the annotations was 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?

The description is two short sentences with no filler. The core function is stated first and the cost is cleanly parenthesized, making it easy for an agent to parse quickly.

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

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

For a simple two-parameter read-only list tool, the description plus annotations, rich schema descriptions, and existing output schema cover the essential invocation context, including cost. It could be more complete by explicitly naming the intended use case relative to sibling tools, but 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 schema already documents both parameters thoroughly, including the pagination offset rule and entityId formats. The description adds no parameter-level detail 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 identifies the resource (a post) and the data returned (reacting people, reaction type, and total), which is enough to distinguish it from sibling tools like posts_comments and posts_info. It lacks an explicit verb like 'list' in the description itself, though the annotation title 'List post reactions' supplies it, 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?

There is no guidance on when to choose this tool over alternatives, nor any explicit exclusions. The schema's entityId description mentions getting ids from companies_posts and that person feeds are unavailable, but the tool description itself offers no usage context or comparison to siblings such as posts_comments or posts_all.

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 read-only, open-world, and idempotent, so the description's job is lighter, but it still adds valuable context: live freshness, a 10-Zooq-credit cost, no extra cost for handle resolution, and free upstream not-found behavior. This meaningfully informs agent decisions beyond the structured 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?

Four sentences carry all the essential information with no filler, front-loading the core output and placing the alternative, cost, and lookup behavior after. Every clause contributes a distinct fact needed for selection or invocation.

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 an output schema and fully documented parameters, the description supplies the remaining operational context: freshness, concurrency handling, cost, not-found policy, and identifier resolution options. Nothing critical 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?

Parameter descriptions alone already cover 100% of the schema, so the baseline is 3. The description adds the operational tradeoff between handle and entityId — handle is auto-resolved at no extra cost while entityId skips the lookup — which aids correct invocation.

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 it returns complete live work history for one person and enumerates the specific per-role fields and the parallel-position grouping behavior. It also distinguishes itself from the overlapping dataset-record tool, so an agent can immediately tell what this tool uniquely provides.

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 to use this tool when freshness, per-role skills, or correct concurrent-role handling are needed, and names profile_full_experience as the overlapping alternative that reads the dataset record. It also clarifies the choice between passing handle versus entityId based on whether the lookup should be skipped.

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 read-only, open-world, idempotent, and non-destructive behavior. The description adds meaningful context by noting live-only flags, the freshness of the snapshot, the distinction from deduplicated records, and the 10-credit cost, which goes beyond what annotations alone provide.

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

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

The description is compact and front-loaded with the core value proposition: a fresh live snapshot. It then adds the key differentiator, the important output field, and the cost in a few tightly scoped sentences 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 low parameter count, rich annotations, and presence of an output schema, the description covers what the tool does, how to call it, what distinguishes it, what it returns, and a usage cost. Nothing essential is missing for an agent to select and 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 documents both handle and entityId parameters and the precedence rule. The description mentions 'by handle or entityId' but adds no new parameter-level detail beyond what is already in the schema.

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

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

The description clearly states this returns a live profile snapshot by handle or entityId and explicitly contrasts it with the deduplicated dataset records returned by other profile/* endpoints. It names the key output (entityId) and distinguishes itself from siblings like profile_full and 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?

The description explains that this tool is for live data, not deduplicated records, and that the returned entityId is needed by other live person endpoints. It does not name specific sibling tools or formal exclusions, but the context makes the appropriate use case reasonably 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 provide readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral details beyond annotations: the 10 Zooq credits cost and the 'resolve once, reuse the id' pattern. It complements the annotations without contradicting them.

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

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

The description is a single focused sentence followed by a short parenthetical note about cost and a reusable-id hint. It is front-loaded with the core purpose and contains no filler or redundant 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?

For a simple one-parameter, read-only, idempotent tool with a fully documented schema and an output schema, the description is complete. It includes the purpose, downstream use context, idempotency guidance, and cost warning. 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% and the parameter description already explains what 'handle' means (the part after linkedin.com/in/ and a full URL works). The description does not add new parameter-specific meaning beyond what the schema provides, so it meets the baseline for high 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 states a specific verb and resource: 'Resolve a public handle to the person entityId used by the live person endpoints'. It distinguishes itself from sibling profile tools by explicitly naming the downstream live endpoints (posts, comments, interests, lookalikes), making its 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 provides clear context on when to use the tool: before calling live person endpoints. It also instructs 'Resolve once, reuse the id', which is practical guidance. However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of the highest bar.

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 bar is lower. The description adds valuable behavioral context beyond the annotations: the 10 Zooq credit cost and the fact that aliases return this exact same record, which helps an agent reason about cost and correctness.

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, purposeful sentences. The first sentence front-loads what the tool returns; the second clarifies the alias relationship and cost. No filler or redundancy, and every clause adds decision-relevant 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?

The description covers content, alias relationship, and cost, and an output schema exists so return-value details are not needed. It does not explicitly state whether at least one of id/handle is required, though the schema strongly implies it; still, the overall picture is sufficiently complete for an agent to select and invoke the tool.

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

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

Schema description coverage is 100%, so the schema already fully documents the 'id' and 'handle' parameters, including the 'Provide handle OR id' instruction. The description adds no additional parameter-level semantics, 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 resource — 'Complete profile in one call' — and enumerates the content (positions, education, skills, certifications, geo, counts, flags). It also explicitly differentiates from sibling profile/* paths by stating they are aliases returning the exact same record, which fully disambiguates the tool from its 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 description provides clear guidance by calling this the 'canonical profile read' and explicitly naming the other profile/* paths as aliases that return the same record, telling the agent to prefer this tool over those aliases. It does not, however, discuss when to choose this over non-alias siblings like profile_enrich or profile_employment_history, so the guidance is not exhaustive.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior, so the description does not need to restate them. The description adds a concrete operational constraint—'Costs 10 Zooq credits'—which is useful beyond the annotations.

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

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

The description is one tight sentence that states the core output and the most important operational caveat. There is no fluff, and the credit cost is appropriately parenthetical.

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 interests query, the schema and annotations already cover inputs and safety behavior, and an output schema is available. The only missing piece is a brief routing note distinguishing this from similar profile tools, but the description is otherwise complete enough to invoke 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 has 100% coverage with detailed explanations for both handle and entityId, including accepted formats and identity resolution. The tool description itself adds no parameter-level information, so the schema does the heavy lifting; a 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 states the resource clearly: 'Entities the person follows' with concrete types (companies, groups, people, newsletters), and the title/annotation 'Get profile interests' reinforces the action. It lacks an explicit verb in the main text, but the meaning is unambiguous and distinct from most profile_* 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 description gives no direct guidance about when to choose this tool over alternatives such as profile_enrich or profile_recommendations. The only operational note is the credit cost, which is helpful but not a usage rationale.

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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by stating the tool costs 10 Zooq credits, which is not present in annotations. It also communicates that the response includes author details and text, giving expectation of the return payload beyond what the annotations imply.

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

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

The description is a single sentence and a parenthetical cost note, efficient and easy to skim. The core resource is stated first, followed by return content and cost. Minor awkwardness in phrasing ('Recommendations written for the person') does not detract significantly from clarity.

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-oriented tool with two optional-by-schema parameters but 100% schema coverage and a known output schema, the description is nearly sufficient. It communicates credits, output content, and the profile-targeting nature. The main gap is the missing usage guidance around when to choose recommendations over other profile tools, but this is covered under Usage Guidelines and does not make the tool unusable.

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 covers both parameters with 100% detail, explaining handle and entityId formats, accepted values, and the OR requirement. The description itself does not add parameter-level meaning, which is acceptable since the schema is fully explicit. Baseline 3 is appropriate here.

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 'Recommendations written for the person' and specifies that author details and text are included, making the tool's purpose clear. It lacks a direct imperative verb like 'get', but the title 'Get profile recommendations' and the handle/entityId parameters strongly indicate the action. No sibling tool is named, but none obviously overlaps with recommendations.

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 guidance on when to use this tool versus alternatives such as profile_enrich, profile_full, or profile_interests. It does not mention scenarios where recommendations are needed, nor does it exclude other use cases. The 'written for the person' wording implies a person-specific profile data retrieval, but no explicit usage context or alternatives are stated.

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

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

Annotations already declare readOnly=true, openWorld=true, idempotent=true and destructive=false, so the safety profile is covered. The description adds the Zooq credit cost and the notion of outputting expanded similar profiles, which is useful behavioral context beyond the annotations.

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

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

One focused sentence with no filler: it states the purpose, the practical use case, and the cost. Every part adds value, and the main idea is front-loaded.

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

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

For a read-only, idempotent lookup with a full schema and a known output schema, the description supplies the essential workflow context: one profile in, similar profiles out, with a credits warning. It doesn't mention that one of handleOrEntityId is effectively required, but the input schema already communicates that.

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

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

The schema already documents both parameters in depth with examples, format preferences, and automatic resolution rules, so the parameter burden is fully handled by the structure. The description itself adds no parameter-specific information, only the general idea that one example profile is the starting point.

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 goal: 'Similar professional profiles — expand a shortlist from one example.' It identifies the resource ('professional profiles') and the action ('expand'), which distinguishes it from companies_similar and jobs_similar, though it doesn't name those alternatives explicitly.

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

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

It gives a clear use case: expand a shortlist starting from one example, and it flags the credit cost as a practical consideration. It doesn't explicitly say when to use this over alternatives or when not to use it, but the intended workflow is understandable.

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

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

The description adds meaningful behavioral context beyond the annotations: it is page-paginated, costs 10 Zooq credits, and returns professional records plus the education link. Since readOnlyHint, idempotentHint, and destructiveHint are already provided, this additional operational detail is valuable. It does not contradict any annotation and gives the agent useful information about cost and pagination.

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 filler. It front-loads the core resource and purpose, then adds pagination, use case, and cost. Every sentence contributes useful selection and invocation 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?

Given the rich input schema, explicit annotations, and presence of an output schema, the description covers the essential selection criteria and key operational facts such as pagination and credit cost. It does not explicitly contrast with alternatives like search_people, but the institutional scope and use case provide enough context for safe selection. Overall it is complete for most agent decision-making needs.

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

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

The schema already covers all parameters with descriptions, including normalized_name and how to discover it via search_schools. The tool description itself adds little parameter-specific meaning, which is acceptable given the 100% schema coverage. No parameter information in the description is missing enough to reduce the score below 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 clearly identifies the tool's resource: alumni and current students of an institution, with professional records plus the education link. It also states the intended use case of recruiting and warm-intro sourcing, which helps distinguish it from general people search. However, it lacks an explicit verb like 'search' and does not directly name a sibling alternative, so it falls short of full differentiation.

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: use this when you need alumni or current students of a specific institution, particularly for recruiting and warm-intro sourcing. It does not explicitly state when not to use it or mention alternatives such as search_people, though the institutional focus strongly implies the boundary. The guidance is clear enough for an agent to select it appropriately in most cases.

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

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

Annotations already communicate read-only, idempotent, non-destructive behavior. The description adds genuinely useful behavioral context beyond the annotations: it is 'cursor-paginated' and costs 10 Zooq credits per request. This is the kind of operational detail that helps an agent calibrate cost and paging behavior, though it could go further by describing result-set 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?

The description is short and front-loaded: scope first, pagination second, cost last. There is no wasted text. The only minor issue is that the second and third clauses are sentence fragments, though they remain easy to scan and parse.

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 schema, output schema, and annotations, the description covers the core search intent plus pagination and cost. However, it fails to explain the key selection distinction from search_companies_live and does not mention the 'dataset'-style nature behind the tool. For a search-oriented tool with many siblings, that missing routing context is a real 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 input schema covers all 13 parameters with descriptions at 100% coverage, so the baseline is 3. The description's phrase 'name or website with firmographic filters' adds only a thin layer on top of what the schema already states; it does not clarify any parameter behavior or format that the schema leaves undocumented.

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

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

The description clearly states the action ('search organizations') and the main input dimensions: name, website, and firmographic filters. However, it does not explicitly distinguish this from the near-twin sibling search_companies_live; the cursor-pagination and credit-cost notes hint at a dataset-style search but do not make the distinction explicit.

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

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

The description says what kind of search the tool performs but offers no guidance on when to choose it over search_companies_live, companies_universal_name_to_id, or companies_name_lookup. There is no when-to-use, when-not-to-use, or alternative-routing information, so the agent has to infer the right choice from sibling names.

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 valuable behavioral details beyond those: 'Offset-paginated,' 'Not-found is free upstream,' and 'Costs 10 Zooq credits.' This gives the agent insight into pagination and cost effects. It doesn't describe rate limits or data freshness nuances, but the most critical behavioral traits are disclosed.

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

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

Each sentence earns its place: the first gives the core action, the second highlights the unique filter, the third routes to an alternative, and the final compact sentence covers pagination, not-found cost, and credit cost. The description is short, front-loaded, and free of 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?

Although the tool has seven parameters, the schema fully documents them, and an output schema exists. The description covers when to use this vs. the sibling, how pagination works, and what the cost consequences are. Combined with the detailed annotations and schema, 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 already explains all seven parameters, including accepted values and caveats. The description reinforces that hasJobs is the key differentiator and that headcount is bucketed, but it doesn't add new parameter-level meaning beyond the schema. This matches the baseline of 3 for high 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 'LIVE company search,' immediately stating verb and resource. It then differentiates itself from sibling search_companies by naming its unique hasJobs filter and bucketed headcount search, while explicitly excluding firmographic filtering. This gives an agent a precise, non-tautological understanding of the tool's role.

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

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

The description explicitly tells the agent when to use this tool (when needing hasJobs or headcount buckets) and when not to (firmographic filtering), directing it to the correct sibling: 'For firmographic filtering... use search_companies instead.' It also mentions cost and pagination, giving practical invocation 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?

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral details beyond those: results are page-paginated, the tool costs 10 Zooq credits, and the returned data consists of job-change events.

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, opening with the core purpose and then adding pagination, use case, and cost. Every sentence carries useful information without fluff or repetition.

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

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

Given the 100% schema coverage, annotations, and output schema, the description is nearly complete. It covers purpose, event types, pagination, intended use, and cost; only an explicit comparison to sibling tools 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 parameters are fully documented in the input schema. The description adds no detailed parameter semantics beyond what the schema already provides, which merits the baseline score of 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 clearly defines the resource as recent professional job-change events and names the specific event types: joined, left, or changed titles. It is easily distinguished from siblings like search_people or search_jobs because it is an event-stream tool rather than a person or job search.

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

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

The description states an explicit use case: 'Built for trigger-based prospecting and territory monitoring.' This provides clear context for when the tool is appropriate, though it does not explicitly name alternatives or 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?

Annotations carry readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond those annotations: the cost ('Costs 10 Zooq credits'), the failure mode ('surfaces as a 422 mentioning entityId; no credits charged'), the pagination behavior ('Offset-paginated'), the exact-match limitation versus LinkedIn's proximate geocoding, and the still-not-usable parameter set (titles, industries, functions, benefits, commitments). This is genuine additional behavioral disclosure. A small deduction because the vague phrase 'Still id-typed and not yet usable' could be more explicit about whether passing values to those params is simply ignored, but overall credit is substantial.

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 economically written — the long `locations` detail is justified because that parameter has the most behavioral nuance, being LinkedIn-specific and exact-match. The top sentence states the core function, the middle covers scoping constraints, and the closing line bundles the credit cost and cross-references. The 'see that parameter' and 'see the note on `locations`' cross-references avoid repetition across similar filters. Slight deduction: the cross-reference style requires the agent to hunt through multiple parameter definitions, and the note about unusable filters is slightly terse given how central it is to correct invocation.

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, complete documentation is hard, and this description rises to the challenge. It covers: which filters work and which do not, how to source external ids, how pagination works, how result ids are consumed downstream, the cost in credits, and the error behavior with no charge. The output schema covers return values, so it need not explain those. An agent could invoke this tool correctly with high confidence from the description alone, which is the defining test for this dimension.

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 would be 3, but the description goes far beyond the schema's bare property definitions. For `locations` it provides a step-by-step discovery procedure (LinkedIn search box, address-bar geoId extraction), a concrete example, case-sensitivity warning, and an exact-match behavioral caveat. For `titles` it clarifies that the schema's 'Title id(s)' means NOT free text, cross-references the `keyword` parameter, and names the upstream rejection error. For `companies` it explains how to obtain an id from job payloads and names the source tool (companies_jobs). This is exemplary parameter enrichment that meaningfully changes how an agent would use the tool.

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

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

The opening line 'Job/opportunity search with the full filter set' clearly names the verb (search) and resource (jobs), and is immediately distinguishable from sibling search tools: search_people, search_alumni, search_companies, search_job_changes are all individually named. The description goes further than any sibling by explaining the exact-match location semantics and cross-referencing consuming tools (jobs_details_v2, jobs_similar, etc.), making the tool's identity 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 explicitly distinguishes free-text matching from id-typed filters: 'Use `keyword` for free-text role matching instead' and 'NOT free text: a title like Senior Full Stack Developer is rejected upstream'. It also warns that LinkedIn shows proximate results while this search is exact-match, advising 'Prefer a CITY id over a country id'. The idempotence and read-only safety profile are already covered by the annotations, so the description's job is to route the agent's parameter choices, which it does thoroughly.

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 two meaningful behavioral facts not in the annotations: cursor-based pagination and a 10-credit cost, both of which help an agent decide whether and how to invoke 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?

Two short sentences deliver the core search scope upfront, then tack on pagination and cost in a compact parenthetical. Every word earns its place, and there is no restating 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?

With 33 parameters fully documented in the schema and an output schema present, the description does not need to explain return values. However, it omits the dataset-versus-live distinction that separates this tool from the similarly named search_people_live, which is a notable gap in an otherwise well-covered 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 every parameter is already individually documented. The description's filter summary (name, title, company, skills, education, tenure, geography) offers only high-level categorization and adds no new constraints or relationships beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the verb and resource ('Search professional records') and enumerates the major filter dimensions, so an agent can tell this is a people-search tool. However, it does not differentiate this dataset-backed search from the sibling search_people_live, leaving some ambiguity about which 'search people' tool to choose.

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 such as search_people_live, search_alumni, or search_job_changes. It mentions cost and pagination but provides no conditions, exclusions, or alternative routing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context beyond that: offset pagination, free not-found upstream behavior, and a 10-Zooq-credit cost. These are operationally important details an agent would not know 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 front-loaded: the first sentence names the tool and its unique selling point, the second distinguishes it from its sibling, and the remaining sentences add pagination and cost facts. Every sentence carries distinct, useful information with no filler.

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

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

The description covers uniqueness, when to use this tool vs. search_people, pagination behavior, cost, and an important data-domain caveat. Combined with 100% parameter schema coverage, rich annotations, and an output schema, nothing essential is missing for an agent to select and invoke 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 has 100% description coverage for all 13 parameters, so the baseline is 3. The description adds semantic value by clarifying that currentCompany, pastCompany, and school can be combined together, and by framing pastCompany/currentCompany around 'company-history sourcing.' This goes slightly beyond the individual schema descriptions.

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

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

The description opens with 'LIVE people search' and states a precise, distinguishing capability: it is 'the only endpoint that filters by current company, past company AND school together.' It also explicitly contrasts itself with search_people, making the resource and function 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 direct routing guidance: 'use this one for company-history sourcing, that one for broad firmographic filtering.' It names the sibling alternative, explains the difference in dataset and pagination style, and leaves no ambiguity about when to pick 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?

The description adds meaningful behavioral context beyond the annotations: partial-match semantics, pagination, and the 10 Zooq credit cost. The annotations already declare readOnly, idempotent, open-world, and non-destructive behavior, and the description supplements rather than contradicts 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?

Two short sentences plus a parenthetical cost note. The main behavior and use case are front-loaded, and every element earns its place without 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 simple, paginated search tool, the description covers purpose, matching behavior, pagination, cost, and intended outcome. The presence of an output schema means return-value details are already handled, so 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?

The schema already describes all three parameters with full coverage, so the description does not need to restate them. It does add context like partial-match behavior and pagination, but this is general behavior rather than parameter-specific 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?

Clear verb and resource: 'Search institutions by name (partial match)' immediately identifies what the tool does and its scope. The mention of discovering an institution's inst_id or normalized_name distinguishes it from the other search_* 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?

The description states a concrete use case: 'Use to discover an institution's inst_id or normalized_name.' It does not explicitly name alternatives or exclusions, but the purpose is specific enough to guide selection among the large sibling set.

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