Alion: company, startup and market intelligence

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

Annotations already declare it read-only, idempotent, non-destructive and closed-world, but the description goes well beyond that: it spells out the automatic moderation rules (3 reports in 7 days → 7-day pause; second pause in 90 days or >5% reports → permanent block; >2% reports or <5% reply rate after 50 messages → new conversations quartered for 14 days). That is exactly the causal context an agent needs to interpret a 'blocked' or 'paused' result, and it links to docs for depth.

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

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

It is a single dense block, but front-loaded with the highest-value field (level) and ordered logically: identity → status → limits → reputation → remediation. The moderation-rule clauses are the bulkiest element and could arguably live in the linked docs, which is the only thing keeping it from a 5.

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

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

There is no output schema, so the description carries the full burden of explaining return values, and it does: it names every field group an agent will receive (level, status, reasons, usage vs limits, five reputation counters plus two rates). It also explains how to act on the data ('how to rise a level'). Nothing an agent needs before calling is missing.

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

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

The tool takes zero parameters, so the baseline of 4 applies and the description has no parameter semantics to compensate for. Nothing misleading is added about inputs.

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 enumerates the exact resource returned: verification level, active/paused/blocked state with reasons, today's usage versus limits, 30-day reputation metrics, and level-up path. An agent can tell precisely what this tool reports, and no sibling tool overlaps. The opening phrasing ('Who Alion takes your agent for') is awkward and the verb is implicit, keeping it 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?

Usage is only implied — an agent infers it should call this to inspect its own standing, limits, or reputation. There is no explicit when-to-use framing, no statement of what to call instead for related questions (e.g. market_stats or check_fit), and no preconditions. The self-scoped nature is clear from context but not stated.

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

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

Beyond the read-only, idempotent, non-destructive annotations, the description discloses that the check is free, does not consume message quota, returns fit status, failure reason codes with hints, individual checks, and remaining agent conversations. That is substantive behavioral and output context for a tool with no output schema.

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

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

The description is front-loaded with the key pre-write purpose and packs useful cost/output details without filler. The first sentence is long and dense with filter clauses, but every part earns its place.

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

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

Given the nested input object, lack of output schema, and read-only annotations, the description supplies the missing return semantics: fit status, first failure reason, hints, per-check results, and remaining conversation quota. It also links to docs, making it complete enough for an agent to call correctly.

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

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

Schema description coverage is 100%, so the nested offer fields and person handle are already well documented. The description explains which filters are evaluated, but it does not add parameter-level syntax or constraints beyond what the schema provides, 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 states a specific verb and resource: it checks whether an offer passes a person's own filters. It also distinguishes itself from write/send tools by saying 'Before you write' and clarifying it is free and not counted against messages.

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 trigger is clear: use it before writing to the person, and the cost note reinforces that context. It does not explicitly name send_message as the alternative or state when not to use it, so it falls short of full when/when-not 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 cover safety and statefulness (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true). The description adds useful behavioral context beyond them: results are newest first, returned in compact search shape, the operation is free, and daily cadence is sufficient. It does not explicitly explain that checking advances the last-checked cursor, though the 'since the last check_watch' wording and annotations imply stateful behavior.

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

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

The description is compact and front-loaded: it states the result scope first, then ordering, shape, frequency, cost, and docs. Every phrase carries useful information with no repetition.

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

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

For a one-parameter, low-complexity tool with no output schema, the description covers what is returned, ordering, shape, cost, and cadence. Minor gaps remain around no-new-results behavior and whether the check advances state, but the definition is largely complete for correct invocation.

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

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

Schema description coverage is 100%, and the single watch_id parameter is already documented as the w_... id from watch_search. The description adds no further parameter details such as format or validation beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description names a specific operation and resource: retrieving what appeared in a watched search since the last check. It also enumerates the returned result types (job postings, companies, people), ordering (newest first), and shape (compact search shape), and explicitly distinguishes the initial watch creation step by naming watch_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?

It gives clear usage context: call this after watch_search to see new results since the last check, and notes that daily checking is enough. It does not explicitly exclude alternatives such as list_watches or describe failure/no-new-results cases, so it falls short of full when/when-not guidance.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true; the description adds genuinely new behavioral facts: what is destroyed (the watch and its remembered state), the observable post-condition (check_watch returns not_found), and cost (free). That is exactly the added context the annotations don't carry.

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 tight sentence sequence: effect, destruction scope, post-condition, cost, docs link. Front-loaded with the primary action and no filler.

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

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

For a destructive single-parameter mutation with rich annotations and a 100%-documented schema, the description covers destruction scope and post-state well. Only minor gaps remain (no auth/permission note, though 'Free' implies no billing), and no output schema exists so return values needn't be explained.

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

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

Schema coverage is 100% and the single watch_id parameter is already described as the w_... id from watch_search, so the schema does the heavy lifting. The description adds no format or lookup guidance beyond what the schema states; baseline 3 applies.

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

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

States a specific verb (stop watching / delete) and resource (a watch), and explicitly names the effect relative to siblings: check_watch will answer not_found. An agent can distinguish it from watch_search and check_watch without inspecting any schema.

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

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

Implies the use case clearly (stop watching a saved search) and names the downstream consequence via check_watch, which helps an agent reason about alternatives. It doesn't spell out exclusions or point at watch_search as the way to undo/recreate, but the context is unambiguous.

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

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

Annotations already declare readOnly/idempotent/non-destructive/non-open-world, so the safety profile is covered. The description adds genuinely new behavioral context: the operation is billed against account credits, name lookups route through resolve_company, and results carry per-source freshness/verification stamps. 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 purpose is front-loaded, but the body is one enormous run-on colon-list enumerating dozens of return fields. Since an output schema already exists, this enumeration is largely redundant and makes the description far larger than needed for tool selection.

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, the description need not explain return contents; it correctly covers identification options, cost, and use contexts, which is sufficient for correct invocation. It lacks explicit sibling routing, keeping it below the top mark.

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

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

Schema description coverage is 100%, so the schema already documents all four identifiers, including 'prefer the domain when you have it.' The description's one semantic addition ('a name goes through resolve_company') largely duplicates the schema's own note that name is 'matched like resolve_company.' Baseline 3 for high coverage 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 opening 'Everything Alion knows about one company' plus the explicit use cases (due diligence, account research, competitor/supplier check) state a clear verb and resource. It does not, however, distinguish itself from siblings like search_companies, similar_companies, or get_job, and the remainder reads as a return-field inventory rather than purpose. Clear but not sibling-differentiated.

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

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

It names concrete contexts ('for due diligence, account research, a competitor or supplier check') and discloses the credit cost ('a few cents a profile'), which helps an agent decide whether to call it. It stops short of stating when-not-to-use or explicitly routing to a cheaper alternative such as search_companies.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-annotated behavior: chronological ordering ('oldest first') and an incremental-delta mode via since_message. It says nothing about result volume, rate limits, or what happens when since_message is out of range.

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

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

Two tight sentences with no filler, and the incremental-fetch instruction is placed after the shape of the result, which is the right reading order. The opening clause is slightly convoluted ('The status of your message ... and the conversation') but nothing is wasted.

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

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

With no output schema, the description does carry the burden of describing returns and partially does so (status enum values, conversation ordering). The critical gap is provenance: nothing explains how to obtain conversation_id, so an agent with zero context may not know how to call this against a specific thread.

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 only 33%, so the description must compensate and largely does not. It clarifies since_message ('the last id you saw') — though that label conflicts with the schema's integer type — while conversation_id is undocumented in both schema and description, and message_id is only covered by the schema itself.

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

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

The description names the resource (a conversation with a person) and what it carries (message status plus the conversation, oldest first), and the title 'Read a conversation' supplies the verb. However, it is phrased as a noun clause rather than a verb+resource statement, and it never distinguishes itself from the sibling list_conversations, leaving the agent to infer that this reads one thread while the sibling enumerates many.

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?

'Pass since_message (the last id you saw) to get only what is new' gives concrete polling guidance for incremental fetches. But there is no statement of when to use this versus list_conversations, no prerequisite telling the agent where message_id or conversation_id come from, and no when-not guidance.

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

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

Annotations cover read-only/idempotent safety, and the description still adds meaningful behavior: the prompt-injection warning to treat employer text as data, the fact that removed or moderated postings aren't served, a per-call cost, and the description_truncated indicator. These go well beyond what annotations and schema 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 content is dense but front-loaded with the tool's purpose, and the long first sentence earns most of its length by enumerating distinct record components. The prompt-injection and cost notes are placed after the core definition. Slightly verbose in listing every return component when an output schema already exists.

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?

An output schema exists so return values need no explanation, yet the description still covers identification methods, default vs html format, truncation behavior, cost, and unsupported (removed/moderated) postings. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the schema already documents id, url, max_chars and description_format thoroughly, so the baseline is 3. The description adds provenance value by telling the agent that the id comes from search_jobs and that url can be an alion.io/job link, its slug, or the original posting url, which helps selection beyond the field 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?

States a specific verb+resource (get one job posting) and enumerates exactly what the full record contains, explicitly framing it as 'everything search_jobs returns plus' the description, tech list, requirements, benefits, lifecycle journal and trust flags. This distinguishes it from search_jobs without the agent needing to open either schema.

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

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

Routes the agent clearly: identify the posting by Alion id (noting it comes from search_jobs) or by url, and it names search_jobs as the origin of the id, implying this is the detail-fetch counterpart. It also states that removed/moderated postings are not served and that each call costs 1 unit, but offers no explicit 'when not to use this' beyond the implicit list-vs-detail split.

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?

Goes well beyond the readOnly/idempotent annotations: it discloses that the response is privacy-filtered to the caller's trust level, explicitly lists what is never returned (email, phone, messengers, birth date, resume file), warns that profile content is data not instructions, states each read is visible to the person, and gives concrete per-trust-tier quotas. That is unusually rich behavioral context.

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

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

The first clause front-loads the core purpose and the never-returned list is a useful early boundary, but the returned-field enumeration and the four-tier quota sentence are long and dense. It stays under control and every sentence carries information, yet the rate-limit roster could be compressed.

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

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

With no output schema, the description appropriately enumerates the returned field groups, and it also covers privacy filtering, safety warnings, side effects (read is visible to the person), cost, and quota limits. An agent can call this correctly without any other source.

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 documents the accepted handle and URL formats for the single `person` parameter, so no additional parameter meaning is needed in the description. The description adds nothing about the parameter, 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 open profile of one person" gives a specific verb (read) and resource (single person profile), and the enumeration of returned fields makes the scope unmistakable. It is clearly distinct from sibling tools like search_people or match_people, which return many people rather than one.

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

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

Usage is only implied: the singular "one person" plus the schema note that the handle comes from a search row hints that search_people must precede this call, but the description never says when to use this versus search_people, get_company, or check_fit. There are no explicit exclusions or alternatives named in the description itself.

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

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

Annotations already establish the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add behavior. It does: newest-first ordering, the two fields returned per conversation, and the 'changed since' semantics of the filter. It stops short of saying whether results are paginated or capped.

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

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

Two tight sentences front-load the resource, ordering, and return shape, then the one parameter tip. The docs URL is padding for an agent but harmless and short.

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

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

With no output schema, the description's note about status and last activity carries the return-value burden, and it does so adequately. Missing only pagination/result-limit behavior for a list endpoint – a minor but real gap for a listing 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 coverage is 0% – 'since' is a bare string with no description – so the description has to compensate, and it does by specifying the format (ISO date) and the meaning (what changed since your last look, i.e. filter on update time rather than creation time). That is a meaningful lift over the bare schema; only the omission case is unaddressed.

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 ('list') plus resource ('your agent's messages to people'), and adds ordering ('newest first') and returned fields ('status and the last activity'). 'List' implicitly distinguishes it from the singular sibling get_conversation, but the description never names that alternative explicitly.

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

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

It gives one clear usage cue – use 'since' to poll for what changed since your last look – which is genuinely useful for an incremental-fetch pattern. However, it never says when to use this versus get_conversation, nor does it mention the effect of omitting 'since' (presumably a full listing) or any paging limits.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds useful context beyond annotations by stating the operation is 'Free' and listing the returned record fields, which helps an agent understand what data to expect.

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

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

The definition is a single front-loaded sentence plus a short cost note and documentation link. Every element is useful and there is no wasted text.

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

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

With no parameters, no output schema, and rich annotations, the description does enough by enumerating returned fields and noting the operation is free. Minor gaps remain around field formats and explicit sibling routing, but an agent has enough to call it correctly.

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

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

The tool has zero parameters, so the baseline is 4. There is no parameter meaning to document, and the schema is fully empty as expected.

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 'the watched searches of this agent' and enumerates the returned fields (id, kind, label, filters, timestamps). It is distinguishable from nearby tools like check_watch and delete_watch by its plural, agent-scoped listing focus, though it does not explicitly name those siblings.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as check_watch or delete_watch. The usage is inferable, but the description does not state the conditions that select this tool or mention any prerequisites.

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

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

Goes well beyond the readOnly/idempotent annotations by disclosing cache TTL (up to 6 hours), partial-result semantics ('named under partial and its figures are null ... repeat the call in about a minute'), null-vs-zero percentile behavior under 5 postings, and a 2-unit cost per call. These are exactly the operational traits an agent needs, though the retry guidance is somewhat buried mid-paragraph.

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?

Purpose and return blocks are front-loaded and no sentence is pure filler, but the definition is one dense paragraph mixing inputs, ten output blocks, caching, and billing. It would scan better with structure, though for a 15-parameter statistical tool the length is largely earned.

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

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

Covers inputs, output blocks with sample sizes, null-handling, partial-result recovery, caching, and cost — everything needed to invoke and interpret the tool correctly. The output schema exists, so the return-value prose is redundant-but-harmless rather than a gap.

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

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

Schema description coverage is 100%, so per-parameter meaning is already documented. The description only restates the filter list and adds the 'same as search_jobs' framing; window_days' reach is clarified only marginally beyond the schema's own wording. Baseline 3 is appropriate.

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

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

States a specific verb+resource (aggregate statistics) and enumerates the exact questions it answers, making its role distinct from the sibling search/list tools. An agent can tell immediately that this is the analytics tool rather than a posting-lookup tool.

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

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

Explicitly names the sibling it pairs with ('Takes the same filters as search_jobs', 'Drill into any figure with search_jobs and the same filters'), giving both the alternative and the condition that selects it. It also implies the when-not case: individual postings belong to search_jobs, aggregates to this tool.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context on its own: free of charge, per-network daily quotas that scale with trust level (anonymous vs SIWX wallet vs Alion account vs verified company), and how ranking works (role and place are hard filters, technologies score and explain themselves in each row). That is exactly the kind of information the schema cannot carry.

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

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

It is front-loaded: purpose and input modes first, then ranking logic, then usage routing, then cost and quotas. Every sentence carries information, though the trust-tier quota sentence is long and could be compressed, and the trailing docs URL is a small tax on length.

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

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

For a 24-parameter, zero-required, no-output-schema tool, the description covers the essentials: how to invoke it three ways, what filters bind versus rank, what a result row tells you, and the quota ceiling that could block a large sweep. Minor gap: it does not mention pagination via cursor or the 100-row paging cap that the schema hints at.

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 already 92%, so the baseline is 3. The description earns more by explaining the semantics the schema never states: that role and place act as hard filters while technologies are a ranking signal, and that the return rows carry a 'why'. Comma-list conventions and budget behaviour are repeated from the schema rather than extended.

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 sentence names the specific verb and resource ('The best people for one vacancy') and immediately states the two input modes (job_id/job_url or a described role). It explicitly contrasts itself with search_people, so an agent can distinguish it from its closest sibling without opening the schema.

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

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

It says plainly when to use it ('when you hire for a concrete role') and names the alternative with its own condition ('search_people when you browse'). The three accepted invocation styles are enumerated, leaving nothing 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?

Beyond the readOnly/idempotent annotations, it discloses ordering (newest first), that results are postings already matched to the profile, per-item metadata (matched timestamp, seen-on-site flag), the auth prerequisite, the account_required error, and that the tool is free. These are exactly the operational facts annotations cannot 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?

Front-loads the identity of the feed and packs payload/ordering details into one dense sentence, with auth and cost as short follow-ups. Slightly over-stuffed with parentheticals (e.g., '/matches feed') but no sentence is wasted.

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-param read tool with no output schema, it covers auth requirements, error behavior, ordering, and the shape of returned items, which is most of what an agent needs. The one remaining gap is the lone limit parameter, which is left entirely unexplained.

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

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

There is one parameter (limit, default 10, max 20) with 0% schema description coverage, and the description never mentions it — no indication of what limit controls or that results are capped at 20. With low coverage the description is supposed to compensate, and it does not.

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

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

States a specific verb and resource: 'The job postings Alion matched to the signed-in account's profile (its /matches feed)', plus the ordering (newest first) and payload shape (compact posting, match time, seen flag). This clearly separates it from siblings like search_jobs (search) and match_people (people side of matching).

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 scopes use to an assistant acting on behalf of a person connected to their own Alion account via OAuth or API key, and states the failure mode without an account ('answers account_required'). It does not name sibling alternatives or exclusions (e.g., when to prefer search_jobs over this feed), so it falls 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: it discloses per-call cost (1 unit), exact vs registrable-domain matching, name-match confidence tiers including _ambiguous, and the ats_board/partial coverage distinction where open-job counts become a lower bound. These are behaviorally load-bearing details an agent could not get from the schema.

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

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

Dense and front-loaded: purpose, return fields, resolution semantics, sequencing, cost, then docs link. The long enumeration sentence is somewhat run-on, but nearly every clause carries information an agent needs.

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 resolver with 4 optional params, an output schema, and rich annotations, this is complete: entry conditions, matching semantics, the confidence taxonomy, cost, and next-step routing are all present. Return values are additionally sketched despite the output schema carrying them.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real semantic value: it explains how each input kind resolves (domain = exact or registrable domain, e.g. jobs.acme.com -> acme.com; name = confidence-scored with candidate list). That interpretation of match behavior is not 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?

Opens with a specific verb+resource ('Find the company record behind a domain, a url or a name') and enumerates exactly the fields returned, so the agent knows this is a resolver, not a fetcher. It explicitly distinguishes itself from siblings by naming get_company and search_jobs as downstream consumers of the id it produces.

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?

States the trigger ('whenever you only have a name or a domain') and the sequencing rule ('Call this first ... then pass the id to get_company or search_jobs'). The alternative path is fully specified, leaving nothing 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 read-only, idempotent, non-destructive semantics, but the description adds a lot beyond them: opaque-cursor pagination, default ordering by recent hiring, agency exclusion, and the cost/free-allowance implication of detail=compact. It doesn't mention rate limits or result-count caps beyond the schema's limit maximum, which keeps it just short of a 5.

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

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

Front-loaded with purpose, then use cases, then behavior, then routing — good ordering. The dense filter enumeration is long but each clause carries distinct capability information; only minor compression could be gained.

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 23-parameter search tool with an output schema, the description covers scoping, ordering defaults, pagination, exclusions, cost trade-offs, and sibling routing. Nothing an agent needs in order to call it correctly is missing, and the output schema handles return-value detail.

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

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

Schema coverage is 100% so the schema already documents all 23 parameters, yet the description adds cross-parameter semantics: sector scoping changes meaning of hiring=true/sort=recent_hiring, raised_since means any venture round when funding_stage is absent, technology is read from job postings, and A/B/C levels are defined. These are genuine additions beyond the field descriptions, though not every parameter gets extra context.

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

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

States a specific verb+resource (find companies in Alion's live company graph) and enumerates the dimensions the search covers (name/domain, country, size, industry, funding, technology, hiring). It explicitly distinguishes itself from siblings by naming similar_companies and get_company for their distinct cases.

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

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

Gives concrete use cases (market maps, competitor lists, deal-flow scouting, tech-adoption research) and explicit routing rules to the alternatives for lookalikes and single-company depth. It also states a default exclusion (staffing agencies) and how to override it, which is real when-to-use guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond that: newest-first default ordering, opaque cursor pagination with the requirement to keep other arguments identical, AND-combination of filters, empty-list-plus-warning on unknown filter values, default exclusion of staffing agencies and intermediaries, a per-call cost of 1 unit, and the trust verdict vocabulary (ok, stale, ghost). These are operational traits an agent cannot infer from the schema.

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

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

Front-loads scope and row content, then ordering, pagination, filter behavior, the agency exclusion and the sibling redirect — a sensible priority order. It is a single dense block and the row-field enumeration is long, but every sentence carries operational information rather than 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 22 optional parameters, an output schema and read-only annotations, the description covers everything an agent needs to call it correctly: source coverage, ordering, pagination, filter composition, failure mode on bad values, default exclusions, cost and a docs link. Nothing material 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 nonetheless reinforces key semantics — sort=salary changes ordering, cursor continuation contract, filter ANDing, and what include_agencies actually admits (job boards, talent marketplaces reposting other employers' roles). It adds meaning around filter interaction rather than merely restating 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?

States a specific verb and resource (search job postings) plus the source corpus (employer ATS boards, career pages, partner feeds) and geographic bias. It explicitly contrasts with market_stats and lists what each row contains, so an agent can tell exactly what this returns versus get_job or search_companies.

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

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

Gives concrete use cases ("who is hiring X in Y", monitoring a company's openings, pulling a sample) and an explicit redirect: for counts, pay percentiles or who hires most, call market_stats instead of paging. It does not explain when to prefer get_job or search_companies, so routing among the other siblings is left implicit.

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

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

Annotations already cover read-only/idempotent/non-destructive, but the description adds substantive context: only people open to offers who left their profile open to agents, emails and phones are never returned, the tool is free, and per-trust-tier rate limits (50/20, 100/50, 1,000/200, 5,000/1,000 per day). That is real behavioral disclosure beyond the structured hints, though pagination/depth limits live only in the schema.

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

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

Front-loads purpose and filter surface, then result shape, then eligibility/privacy/limits/next steps — a sensible order. It is dense and run-on in places (the long semicolon chain of filters and the four-tier quota sentence), but nearly every clause carries information an agent needs.

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 22 parameters and no output schema, the description does the heavy lifting: it enumerates the card fields returned (handle, headline, seniority, skills with years, recent jobs, pay expectation, 'why'), states eligibility/privacy restrictions, quotas and next-step tools. Nothing an agent needs to call this 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 91%, so the schema carries most parameter meaning. The description still adds the cross-parameter rule that one of role/technology/query/company is required and the rest narrow, which is nowhere in the schema (required array is empty), plus framing of what people must have matched ('every one is required' for technology is in schema, but the 'narrow' semantics is description-level).

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

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

States a specific verb and resource ('Find people on Alion for a role') and immediately enumerates the eligible populations (engineers, data, product, designers, founders) plus the filter surface. An agent can tell this is a candidate-search tool apart from get_person, check_fit and send_message, which are named in the follow-up workflow.

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

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

Gives an explicit invocation constraint ('at least one of role, technology, query or company is required, the rest narrow') and a clear next-step workflow (get_person to read, check_fit before writing, send_message to write). It does not explain when to prefer this over the close siblings match_people or similar_people, so the alternative-selection guidance is incomplete.

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

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

Beyond the annotations, the description discloses critical behavior: delivery depends on the person's filters and platform rules, blocked messages return reasons and hints while the person never sees them, messages may be queued up to 7 days, and free usage is limited by trust level. These details materially improve an agent's ability to invoke the tool correctly and avoid violating platform constraints.

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 front-loaded with the core action and then adds operational detail. It is denser and longer than ideal, especially the enumeration of rejection reasons and free-tier limits, but those details are relevant to correct use and are not merely redundant with structured fields.

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

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

For a complex, open-world write tool with nested parameters and no output schema, the description is sufficiently complete: it explains delivery outcomes, failure reasons, queuing, usage limits, continuation behavior, response handling via get_conversation, and the docs link. An agent has enough context to call the tool and interpret the main outcomes.

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 high at 89%, so the schema already documents most parameters. The description still adds useful meaning by summarizing the structured offer fields, explaining message length and language expectations, clarifying that on_behalf_of company must be verified, and noting that continuation uses conversation_id plus message only.

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

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

The description uses a specific verb and resource: 'Start a conversation with a person in their Alion messages.' It clearly distinguishes a first structured offer from continuing an existing conversation via conversation_id, so an agent can identify the tool independently of 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 gives strong contextual guidance: first messages are structured offers with a specific shape, continuation uses only conversation_id and message, and answers arrive via get_conversation and set_webhook. It also explains when delivery is blocked by filters/rules, though it does not explicitly direct users to prerequisite discovery tools such as search_people.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so mutation and external exposure are covered. The description adds genuinely non-obvious behavior: payloads are signed POSTs, the HMAC secret is returned only once ('once'), and the signature header is X-Alion-Signature — all facts an agent could not derive from structure. It stops short of saying what happens to an existing webhook when a new URL is set (replace vs. error).

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

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

One dense paragraph with no filler; the event list, the secret-shown-once caveat, the removal sentinel, and the docs link all earn their place. It is slightly parameter-first rather than action-first, which delays the key 'this sets a webhook' framing by a few words.

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

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

For a one-parameter mutation with no output schema, the description is nearly self-sufficient: it covers the input contract, the return value (secret returned once), and the removal path. What remains unstated is replacement semantics when a webhook already exists and how to rotate the secret without losing it.

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 'url' parameter has zero schema description coverage, so the description must carry it — and it does: it specifies 'public https', ties the parameter to what will be delivered, and defines the sentinel value (empty string removes the webhook). Missing only format/length edge cases to reach a 5.

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 conveys that this tool registers a public HTTPS URL to receive agent events, and that an empty URL deregisters it, so the underlying action is inferable despite never using an explicit verb like 'set'. It clearly belongs to a different domain than every sibling (search/agent_status/conversation tools), so no ambiguity arises.

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 enumerates the exact event types the webhook will receive, which implies when to use it (push-based delivery of message/agent events), and it explicitly documents the removal case: 'Pass an empty url to remove it.' However, it never contrasts with pull-based siblings like get_conversation or list_conversations, and gives no prerequisites beyond 'public https'.

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

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

Beyond the annotations (readOnly, idempotent, closed-world), the description discloses genuinely non-obvious behavior: staffing agencies and job boards are excluded from results, ambiguous company names are reported in warnings rather than silently resolved, and compact reads are cheaper with a free daily allowance for connected assistants. This is exactly the kind of cost and edge-case context the annotations cannot carry.

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

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

It's a single dense paragraph, but the defining clause ('lookalikes of one company: companies that share...') is front-loaded before the use cases, exclusions and cost notes. Nearly every clause carries information an agent needs; the trade-off is that the run-on structure makes it harder to scan than a short bulleted form.

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

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

For a filtered similarity-search tool with an output schema already defining the return shape, the description covers the remaining gaps: what similarity means, what is intentionally excluded, how ambiguous input is handled, and the cost model. Nothing an agent needs in order to call it correctly is absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: 'company' accepts an Alion id, domain or name and ambiguity surfaces in warnings, and 'country' acts as a hard narrowing filter on office location. The detail=compact field list largely duplicates the schema description, which caps this below 5.

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

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

The description names a specific verb and resource ('lookalikes of one company') and then defines similarity concretely: shared industry segments, technologies named in job postings, headquarters country and a near size band. It also distinguishes itself from the sibling search_companies by describing rows as 'a company (as in search_companies) plus similarity', so an agent can tell the two apart without opening either schema.

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

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

It gives concrete use contexts — market map, competitor scan, prospect list from a best customer, alternatives to a supplier — plus a narrowing rule ('Narrow to one country with country'). What's missing is explicit negative guidance: it never says when to prefer get_company, resolve_company or search_companies instead, so routing is implied rather than stated.

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

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

Annotations already declare this a safe, idempotent read, and the description still adds substantive information beyond them: the tool is free, and quotas vary by credential tier (50 reads/20 searches anonymous up to 5,000/1,000 for verified companies), which directly affects how an agent should pace calls. It also states the matching logic (role family plus shared skills) and links to docs, all of which is invisible 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?

Front-loaded with the purpose clause, then the intended use case, then limits, then a docs link — a sensible information order with no filler. The quota sentence is long and enumerates four tiers inline, which costs readability slightly, but every clause carries decision-relevant 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 3-parameter, read-only tool with no output schema, the description covers the matching basis, the optional country filter, the credential/quota model, and where to read more. The main gap is that it does not hint at what each result row contains or whether match rationale is returned, which an agent might want; otherwise nothing needed to call it correctly is missing.

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

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

Schema coverage is 67%, with 'person' and 'country' documented in the schema; the description's 'optionally in one country' reinforces that country is a filter, not a requirement. The 'limit' parameter (1-20) is documented only by its numeric bounds and gets no semantic framing in the description, such as what a sensible shortlist size is. Baseline 3 is appropriate given the schema carries most of the load.

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

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

The description states a specific verb-like operation and resource: find 'People like a given one' and defines the similarity basis as 'the same role family and the skills they share, optionally in one country.' This is far more precise than the title alone and lets an agent distinguish it from get_person or search_people. It stops short of explicitly naming the nearest siblings (match_people, search_people), so it is clear but not fully differentiated.

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

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

'For a shortlist built from a good candidate' implies the triggering situation — you already have one strong profile and want more like it — which is useful context. However, it gives no explicit exclusions or alternatives: nothing says when to use search_people or match_people instead, nor what happens if the seed profile is unknown or sparse. Usage is implied rather than directed.

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?

Goes well beyond the annotations: requires an account, describes a two-step token/publication flow that explains the non-idempotent, write-ish nature, lists refusal cases (public mail domains, lookalikes, sanctions lists), and states the payoff (domain display, check mark, recruiter-visible data, highest limits). That is substantial context an agent could not infer from readOnlyHint=false / openWorldHint=true 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?

One dense paragraph, front-loaded with the goal and the branch conditions; nearly every clause carries information. Slightly crammed with benefit details (check mark, recruiter visibility, limits) that could be trimmed, but nothing is truly wasted.

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

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

With no output schema, the description should signal what comes back; it implies a token on the first call and a verified state after the second, which is adequate. It stops short of enumerating the response fields, a minor gap for a multi-step flow.

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 already documents `domain` at 100% coverage, but the description adds real semantics: the domain must be a genuine company domain because public mail domains and lookalike domains are refused. That constrains inputs in a way the schema does not.

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

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

States a specific verb+resource (prove/verify that an agent writes for a company) and defines what "verified" concretely means. It is distinguishable from lookup siblings like get_company or resolve_company, though it never names them explicitly.

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

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

Gives a clear precondition (an Alion account is needed) and spells out the two branches of usage: instant verification if the company was claimed with a work email, otherwise the well-known file dance with a re-call. No explicit 'when not to use' or sibling routing, which is the only gap.

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?

Goes well beyond annotations by disclosing that the first page is returned immediately (newest first, compact), that a `watch_id` is issued for later diffing, and that there is a hard quota of 20 watches per agent with the account/wallet/network-client identity model spelled out. Annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) are consistent with a non-destructive create-with-quota operation, and the description adds the cost ('Free') and docs link.

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

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

Front-loaded with the core value proposition (save and come back for what's new) and dense with useful detail; almost every clause carries information. It is a single unbroken block with stacked parentheticals, which slightly hurts scanability.

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 3 params, a nested object, no output schema and no annotation for return shape, the description still tells the agent what comes back (first page now, compact, newest first, plus watch_id), how to consume it later, and the quota ceiling. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 67% and the schema leaves `filters` as an opaque object, but the description supplies an inline example filter set and specifies that its keys are the arguments of the corresponding search_* tool, with cursor and limit ignored. That is meaning the schema does not carry, so it more than compensates for the coverage gap.

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

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

States a specific verb and resource — save a search over jobs/companies/people and retrieve what is new — and immediately ties the filters to the `search_jobs`/`search_companies`/`search_people` siblings, so the agent knows this is a persisted wrapper, not a plain search. The pairing with `check_watch` completes the picture of what the tool is for.

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

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

Gives concrete use cases ('a job hunt, a hiring pipeline or a market you follow') and explicitly routes follow-up retrieval to `check_watch`, which is the key alternative-facing guidance. It stops short of an explicit exclusion (e.g. 'use search_jobs directly for a one-off lookup'), so the when-not is only implied.

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