AyHire

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

Annotations already declare readOnly=false, idempotent=true, openWorld=true and destructive=false, so the safety profile is covered. The description adds genuinely useful non-obvious behavior: a 25-person cap, that existing members keep their decision and notes while a new reason replaces the old one, and that the role persists the reason and provenance for display in the web app and get_role. It does not cover failures, permissions, or what happens with an unknown username.

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 but front-loaded: the action and its required reason come first, then limits and merge semantics, then the next tool. A few clauses about display surface ('shown in the web app and in get_role') are borderline but still informative.

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 mutation with annotations and no output schema, the description covers the essentials agents get wrong: reason quality, the 25 cap, re-adding an existing person, and the follow-up scoring step. Missing only error/permission behavior and role_id sourcing, which is a modest gap.

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

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

Schema coverage is only 33%, so the description has to carry weight: it explains that each person needs a one-line plain-words reason and gives a concrete example ('Wrote the MVCC layer of turso: 103 merged PRs titled mvcc'), and it clarifies found_via as 'the search that surfaced them' / 'how they were found'. However role_id is undocumented in both schema and description, and there is no mention of the people array structure beyond the reason.

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

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

Specific verb + resource ('add people ... to a role') with clear scope ('up to 25 at a time'). It implicitly separates itself from the discovery siblings by framing the input as people 'you chose (from any search, or ones you know)', and explicitly hands the next step to score_role_person, though it never names find_people_for_role or search_people as the alternative to use instead.

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

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

Clear context for when to call it (after you have chosen candidates, whether surfaced by a search or known directly) plus an explicit forward reference: 'Then score_role_person scores them.' It stops short of stating exclusion conditions, e.g. that this is not the tool for finding people in the first place.

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, it discloses substantive behavior: 30-day caching with cached=true, 15-25s scrape time, dropped unsourced claims, outside_work scope over the last year, and the activity calendar return. These details materially affect invocation and expectation setting.

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

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

The description is dense and front-loads the alternative tool before detailing scope and behavior. It is somewhat long, but each sentence carries relevant invocation or expectation-setting information.

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

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

For a complex scoring tool with no output schema, the description explains what is returned, how claims are sourced, caching/latency behavior, scope limits, and activity output. It gives an agent enough context to call it correctly and set expectations.

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 useful meaning for refresh by restricting it to explicit fresh-analysis requests, while persist remains covered adequately by 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 states a specific verb and resource: score a GitHub user's public work on four named dimensions, with findings, red flags, top skills, and activity. It also explicitly distinguishes itself from score_role_person, so an agent can select it 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 gives an explicit alternative for role-based evaluation (score_role_person) and a clear condition for refresh=true: only when the user asks for a fresh analysis. The cached-vs-scraped behavior is also stated, removing ambiguity about when the long-running path occurs.

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, which only say non-read-only, open-world, non-idempotent, non-destructive. The description discloses caching (30-day saved analyses are free), throughput (up to 4 new analyses per call, ~20-35 s), a 20/hour limit, and the exact response states pending/limited with limit_resets_at and limit_reason — operational facts an agent cannot infer from structured fields.

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

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

Front-loaded: what it does and returns comes first, then timing, rate limits, and use cases. It is dense with parentheticals (limits, reset fields, plan caveats) but nearly every clause carries operational 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 no output schema, the description supplies the return shape (ranked best-first, totals out of 40, per-user scores, summary, skills, red flags) and the non-final response envelopes pending and limited. For a non-idempotent, open-world, cost-bearing call, that is enough 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% and the single usernames parameter carries its own description and example, so the baseline is 3. The description restates the 25-item cap (also in maxItems) but adds no format, ordering, or duplicate-handling semantics for the array.

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

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

States a specific verb (analyze), resource (GitHub users), and batch scope (up to 25 in one call) returning ranked results with named fields (totals out of 40, four general scores, summary, top skills, red flags). The batch scope plus the explicit mention of find_people_behind_repos makes it distinguishable from the single-user sibling analyze_github_user.

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?

"Use it to compare a shortlist or to score the people find_people_behind_repos returned" gives concrete selection criteria, and it prescribes the follow-up action for pending results ("call again with those"). It never states when to prefer the single-user analyze_github_user, so the exclusion side 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?

Beyond the readOnly/openWorld/idempotent annotations it discloses that the question leaves the system to a third party, that personal details are refused, that answers are cached in the workspace only a few hours, that `state: pending` means polling with retry_after_sec, and that returned text is data rather than instructions. These are exactly the operational and safety facts an agent needs and that 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?

The purpose and example are front-loaded in the first clause, and the remaining sentences carry distinct facts (privacy rules, caching, pending polling, fallback, trust boundary). It is dense and a single unbroken block, which slightly hurts scannability, but no sentence is 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 no output schema, the description takes on the burden of explaining returns and does so: answer text, cited files with links verified against the default branch, async `pending` state with retry guidance, and a `fallback` payload. Nothing material for a correct call is missing.

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

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

Schema coverage is 100%, so all three parameters are already documented, and the description largely restates the schema constraints ('public repo', 'no personal details'). It adds some framing by tying the question to code-only topics and by naming list_workspaces indirectly through the workspace default, but no new syntax or format detail.

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 ('Ask DeepWiki a question about a public GitHub repo's code') and immediately describes the return payload: a generated answer plus cited files linked and verified against the default branch. It is clearly distinguishable from siblings like read_readme, get_repository_knowledge and contribution_profile.

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

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

It explicitly scopes the question content ('ask about the code, not about who wrote it') and routes authorship questions to contribution_profile, while pointing to `fallback` (README plus GitHub facts) when DeepWiki cannot answer. When-to-use, when-not-to-use, and the alternative are all 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 give a safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds the genuinely non-obvious part: cancellation is partial — pending rows are dropped while already-added people persist in the role. The idempotency sentence only restates idempotentHint=true, so it earns no extra credit, and permissions/prerequisites are still unstated.

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

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

Two sentences, front-loaded with the verb and outcome, then the partial-effect caveat. No filler and no restatement of the title alone.

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

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

For a one-parameter mutation with no output schema, the description covers the essential behavioral question (what survives a cancel) and idempotency. It stops short of saying how to obtain the import_id or how to verify the resulting state, which are the only material gaps.

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 0% for the single required parameter, and the description never mentions import_id — no hint about where it comes from (list_imports / get_import) or accepted format. The name is fairly self-evident, which keeps this from a 1, but the description does nothing to compensate 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 ('Stop an import') in the very first words, which cleanly separates it from the surrounding import lifecycle siblings (run_import, get_import, list_imports, import_people). An agent can identify the operation without consulting the schema.

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

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

The effect ('rows not added yet are cancelled') implies the when-to-use case — cancelling an in-flight or partially-applied import — but the description never states a condition or names an alternative. There is no guidance on what to do instead if the import already finished, or how to inspect state before cancelling.

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: it discloses that provider runs in progress are asked (not forcibly) to stop, that already-found results are retained (consistent with destructiveHint=false), and that the call reports settled/in-flight/unknown spend. It also pre-empts the idempotency question by stating repeat calls change nothing, matching idempotentHint=true.

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

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

Four short clauses, each carrying distinct information (scope of stop, effect on provider runs, spend reporting, result retention, idempotency). Front-loaded with the 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?

Since there is no output schema, the description usefully explains what the call reports back, and it covers retention and idempotency for a mutation tool. Remaining gap is sourcing job_id and edge cases such as an unknown or already-completed job.

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

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

With only 50% schema description coverage, the description should compensate, but it never mentions job_id or how to obtain it. The workspace parameter is documented in the schema (including the list_workspaces pointer), so the undocumented required parameter is the real 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 ('Stop a research job') that is unambiguous against siblings like get_research_job and start_research_job. The following clauses immediately define what 'stop' concretely means, so the agent never has to guess the operation.

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

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

The description makes the effect clear ('nothing new is reserved or sent') and signals repeat calls are safe, but never names an alternative or a when-not condition. It does not mention checking status via get_research_job first, nor what to do if the job already finished — usage is only implied.

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

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

Annotations say readOnlyHint=false and idempotentHint=false; the description explains why by disclosing that the run 'saves' the lookups — a real side effect no annotation could spell out. It also discloses the data sources (external LinkedIn/GitHub lookups) matching openWorldHint=true. It stops short of noting cost or rate-limit behavior for the deep path.

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

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

Three sentences, front-loaded with the question being answered, then mechanism, then the return vocabulary, then the sibling relationship. Every sentence 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?

No output schema exists, so listing the possible verdicts and noting that evidence is returned is exactly the right compensation. Only gap is the missing behavior of the deep option and how much evidence is returned, which is minor for a two-parameter check.

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 defines both username and deep. The description adds nothing about the deep parameter's cost tradeoff beyond what the schema's own 'costs more' note provides, so baseline 3 applies.

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

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

States a concrete question and the resource it answers it from (LinkedIn role, GitHub company field, GitHub 'available for hire' flag), plus the exact verdict vocabulary returned. It is clearly distinct from enrich_person despite sharing its lookups, so an agent can tell the two apart.

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 opening question frames when to reach for it, and the closing sentence explicitly explains the relationship to enrich_person (same lookups, shared cost, so calling both is free). No explicit exclusion or prerequisite is given, which keeps it short of a 5.

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

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

Annotations already cover read-only, idempotent, open-world and non-destructive behavior, and the description adds real value on top: it is free, live, takes about 3 s, and truncates PR detail to the newest 10 with size and links. It also warns that commit data exists to catch direct committers. It does not discuss rate limits, auth requirements, or failure modes, keeping it short of a 5.

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

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

Front-loaded with the core purpose, then the payload, then the use case, then cost/latency. The long enumeration of returned fields is dense but each item carries information an agent needs given there is no output schema. Slightly over-packed but not wasteful.

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 carries the full burden of explaining return values and does so thoroughly — counts, date range, truncation to 10 PRs, code-area breakdowns, review activity, commits, and rank. An agent knows what it will get and roughly what it costs before calling.

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

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

Schema description coverage is 100%, with the repo field already documenting 'owner/name or a github.com URL' and username documented as a GitHub username. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('what a developer actually did in one repo') and then enumerates the concrete payload: merged PRs with counts and dates, touched code areas with counts, open PRs, reviews of others' PRs, commits, and contributor rank. This is clearly distinguishable from siblings like list_pull_requests or analyze_github_user, which do not aggregate per-repo contribution evidence.

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: verifying a claim like 'core contributor to the storage engine' or discovering someone's real area in a big project. It does not name which sibling to use instead when the goal is different (e.g., get_person_evidence or score_candidate), so alternatives are left implicit rather than explicit.

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

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

Annotations only declare that this is a non-read-only, non-destructive, non-idempotent, closed-world write, so the description adds real value: it discloses that AyHire auto-generates criteria and a starting search query, and that the role is persisted into the current workspace and mirrored in the web app. It does not discuss duplicate handling or whether a partial failure rolls back the auto-generated criteria, which would have pushed this higher.

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 core action and its key caveats are front-loaded in the first clause, and the override conditions follow logically. It is dense — one long sentence plus one short one — but each clause carries non-redundant information about defaults and side effects.

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

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

For a 7-parameter creation tool with no output schema, the description never says what is returned (presumably a role id needed for follow-on calls like add_people_to_role, set_role_criteria or find_people_for_role). Everything about inputs and side effects is covered, but the return-value gap is a real omission given no output schema exists.

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 would be 3, but the description adds genuine meaning beyond the schema: it explains the conditional relationship between `criteria`/`query`/`language` and the automatic derivation, and that `title` plus `brief` are the inputs to that derivation. It doesn't elaborate on `created_after` or the workspace fallback beyond what the schema already says.

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

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

The description gives a specific verb and resource ('Create a role') and immediately disambiguates the domain term — 'an open position' — so an agent cannot confuse it with an auth role. It also names the downstream intent ('to source people for'), which distinguishes it from create_workspace and other siblings in the list.

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

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

It clearly states the two modes of operation: criteria come from the title/brief automatically 'unless you pass `criteria`', and the GitHub search query is derived 'unless you pass query/language'. That effectively tells an agent not to bother with suggest_role_criteria for the default path. It does not explicitly say when to use this versus list_roles/get_role, but those are trivially distinguishable.

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 only declare the generic write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds a genuinely non-obvious side effect — the newly created workspace becomes active ("switch to it") — and the data-isolation consequence, both of which matter to an agent. It does not cover name-collision behavior or permissions, so not a 5.

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

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

Two short sentences, zero filler, with the creation action and the auto-switch side effect front-loaded before the isolation rationale.

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 creation tool with no output schema and adequate annotations, the description covers the essential behavior including the active-workspace switch. Remaining gaps (duplicate-name handling, what the call returns) are minor but real.

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

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

Only one parameter, and the schema already carries an example and the 1-60 character constraint at 100% coverage. The description's only added signal is that the name typically refers to the client company, which is marginal beyond the schema's own example — baseline 3 applies.

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

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

States a specific verb and resource ("Create a workspace") plus two important scoping facts: it is for another company you hire for, and its roles/shortlist are isolated from your other workspaces. That implicitly separates it from switch_workspace and list_workspaces, though no sibling is named explicitly.

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

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

Gives a clear condition for use ("for another company you hire for") and the motivation (keeping roles and shortlist apart), which is enough for an agent to decide between this and switching to an existing workspace. It stops short of stating exclusions or naming the alternative tool outright.

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=false, destructive=false and idempotent=true, so the safety bar is lower. The description still adds real context beyond them: decisions are visible to everyone in the role's workspace (a social/visibility consequence) and 'none' functions as an undo rather than a new 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?

Three short sentences, front-loaded with the verb and resource, then the state values, then the optional note, then consequences. Nothing is padded or repeated from the name or title.

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

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

With no output schema, the description carries the burden of stating side effects, and it does so for visibility and shortlist propagation. It leaves one notable gap: the reasons parameter's effect on the role's next_round is only explained in the schema, not in the description.

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

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

Schema coverage is 67% and the schema itself documents reasons and feedback_note thoroughly, including the enum values. The description only adds meaning for the decision enum (via 'none (undo)' and 'Optionally add a note'), and is silent on reasons and feedback_note, which carry non-obvious side effects (reasons feed next_round).

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 ('record a decision') and resource (a person in a role), and enumerates the three decision values. It names the downstream consumer get_shortlist, which aids discrimination, but does not distinguish itself from near-neighbours like score_candidate or next_round.

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?

'none (undo)' implies the reversal case, and 'Shortlisted people show up in get_shortlist' hints at where to verify results. However there is no explicit guidance on when to call this versus score_candidate or next_round, and no stated prerequisite that the username must already be in the role.

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

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

Annotations already declare destructive=true, idempotent=true, readOnly=false, but the description adds real consequence detail the annotations cannot: the key stops working immediately on AyHire's side, the website session persists, other agents sharing the key are also affected, and this agent's AyHire tools stop functioning afterward. That is exactly the blast-radius information an agent needs before a destructive call.

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

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

Four short sentences, each carrying distinct information: what it does, when to use it, what survives, and what happens afterward. The effect is front-loaded before the usage conditions, and the user-utterance list is a practical trigger aid 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?

For a zero-parameter destructive tool with no output schema, the description covers effect, scope, side effects on the website and sibling agents, and post-call expectations. There is no meaningful gap an agent would need filled before invoking 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 tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. Nothing in the description misleads 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?

States a specific verb and resource — 'End this agent's connection to AyHire' — with a precise scope ('this agent'). The scope phrase distinguishes it from workspace-level siblings like switch_workspace or invite_to_workspace, and an agent can identify it 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?

Gives explicit trigger conditions ('only when the user asks to sign out, log out, disconnect, remove or forget AyHire here') and an explicit exclusion ('don't try to sign in again unless the user asks to reconnect'). Both when-to-use and when-not-to-use are covered.

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 (readOnlyHint=false, openWorldHint=true, destructiveHint=false) by disclosing the paid external lookup model with concrete prices ($0.001–0.015, up to ~$0.03 with deep), the GitHub-first free tier ordering, and the 30-day result cache. This is exactly the cost/rate/state context annotations cannot express, and it is what lets an agent decide whether a call is affordable.

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 dense sentences, front-loaded with the return payload then cost then guidance; no fluff. The only clause that does not earn its place is '(cached=true is free)', which misnames a parameter and adds confusion rather than signal.

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

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

There is no output schema, so the description must carry the return contract — and it does, listing every field plus the source/confidence metadata per field. It also covers cost, caching lifetime, and the deep-mode escalation, which is everything needed to call this correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description usefully ties deep=true to extra X-bio and name+company searches and explains the refresh/cache cost tradeoff. However it references a 'cached=true' switch that does not exist in the input schema (the real parameter is refresh), which could lead an agent to pass an invalid argument. That stale reference offsets the added value.

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 by scoping to a single GitHub user and enumerates exactly what is returned (LinkedIn URL, headline, current companies, work email, X profile, each with source and confidence). 'For one GitHub user' immediately separates it from bulk siblings like find_people_for_role or analyze_github_users. An agent can tell what this returns 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?

Gives explicit when-to-use guidance ('people the user is seriously considering') and an explicit when-not ('not on every name in a list'), plus cost-based selection guidance for deep=true. It never names a specific alternative sibling (e.g., get_person_evidence or analyze_github_user) to route to instead, which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint/idempotent/destructive=false; the description adds valuable behavior: it is free, nothing is reserved or sent, and it runs against live provider schemas. It stops short of rate limits or latency, so not a full 5.

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

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

Front-loads the key fact (Free / nothing reserved) and packs useful detail efficiently. Some clauses are dense run-ons, but every sentence carries meaning without bloat.

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

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

For a 4-param nested tool with no output schema, it conveys purpose, cost semantics, and the handoff to start_research_job well enough to call correctly. It doesn't sketch the estimate's return shape beyond at_most_usd, a minor gap.

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

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

Schema coverage is 50%, but the description compensates by explaining kind company_people semantics ('who LinkedIn lists with a current role… by title and place if given') and the company-vs-company_id lookup rule (taken only when exactly one company matches). max_results and workspace are left to the schema.

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

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

States a specific verb+resource: it tells what a research job would do and its maximum cost, drawn from live provider schemas, with nothing reserved or sent. It clearly distinguishes itself from start_research_job, the actual job-starting sibling it feeds into.

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 clearly frames this as the free preview step whose at_most_usd feeds start_research_job's max_cost_usd, giving the agent an explicit path to the alternative. It doesn't explicitly state when-not-to-use (e.g. once a job exists), but the context is clear.

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

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

Despite readOnlyHint=false, the description explains the actual side effects: with role_id the search is logged in the role's history, results are marked seen, already-seen people are excluded, and 'Nothing is added to the role: use add_people_to_role.' It also discloses bot/AI-agent exclusion, the location_match:'unknown' semantics, and that the source is free/GitHub-only — context none of the annotations provide.

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

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

The core purpose is front-loaded and every sentence carries operational information (repo/org routing, location caveat, role_id side effects). It is dense and slightly run-on in places, but there is no filler.

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

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

For a 16-parameter tool with no required params and no output schema, the description plus full schema coverage covers what an agent needs: selection between repo/org/query paths, the roles of location and role_id, and the key returned fields (public_member, location_match). Nothing critical is left unexplained before 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 baseline is 3, but the description adds real meaning beyond the schema: page paginates repos (not people), location keeps people with no location marked 'unknown' and 'unknown is never a mismatch', and role_id's seen-filtering semantics including include_seen. That lifts it above baseline.

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

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

States a specific verb and resource — search GitHub repositories, then list the people who contribute most to them, ranked — with the exact scoping knobs (repo, org). An agent can distinguish this 'repo-first then people' tool from the people-first siblings like search_people or find_people_for_role purely from the description.

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

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

Gives clear selection guidance: pass repo for one exact project, org for an organization, and 'Mining several seed repos one after another is often the best way to find strong people.' It also explains role_id behavior. It does not explicitly contrast against sibling alternatives by name (e.g. search_people), so it falls short of a full when/when-not map.

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 mark this as non-read-only, open-world, non-idempotent, and non-destructive; the description goes further by explaining that it saves people to the role, runs the search plan, queries the index first and GitHub live when needed, excludes already-seen people, pages through matching repos, and returns why_found/source/relevance. These details are consistent with the annotations.

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

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

The description is front-loaded with the core action and most sentences add relevant behavioral or usage context. It is dense and somewhat run-on, but given the tool's complexity and the number of alternatives it needs to distinguish, the length is mostly justified.

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

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

For a complex 7-parameter tool with no output schema, the description is complete enough: it explains what is searched, how index versus live GitHub results work, what is returned, what is not done yet, and which sibling tools to use for adjacent tasks.

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 86%, so the schema already carries most parameter documentation. The description still adds useful semantics beyond the schema: query/language override the search for this run, include_seen brings back people the role has already seen, and page 2 onward reads the next repos.

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: run the role's own search and save everyone it finds to the role. It clearly distinguishes this from manually choosing people with search_people/find_people_behind_repos/search_commits plus add_people_to_role, and from next_round for feedback-learning rounds.

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 explicit when-to-use guidance and alternatives: use this tool to run the role's saved search, use the search tools with role_id plus add_people_to_role to choose people yourself, call score_role_person afterward for scoring, and use next_round for feedback-driven rounds with required constraints.

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: 'Free and read-only' confirms cost profile, 'Never calls GitHub or LinkedIn' is a concrete side-effect guarantee, and the section glosses disclose critical interpretation caveats ('not confirmed employment', 'proves nothing either way', 'maybe a namesake', coverage 'never a complete roster'). Those warnings are exactly the context an agent needs to report results honestly.

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 key framing ('Free and read-only'), then the resource, sections and the onward call. It is one very dense run-on sentence, and the parenthetical caveats make it harder to scan, 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 5-parameter read tool with no output schema, the description covers identity inputs, section semantics, paging and interpretation caveats. It does not describe the shape of the returned payload or how map_id and request_id relate, which keeps it from 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?

With only 20% schema coverage the description must carry the load, and it does: it defines the meaning and caveats of every section enum value and explains that page/section retrieve one section 50 at a time, plus that either map_id or request_id identifies the map. The workspace parameter is left to the schema's own description, a minor 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 the specific verb and resource ('a company map by map_id or request_id') and enumerates exactly what the map contains (orgs, coverage, and the six named sections). An agent can distinguish this read tool from start_company_map and resolve_company 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?

Explicitly routes the agent onward: 'to go on with a map, call start_company_map with its request_id', and gives paging guidance ('give section and page for one section 50 at a time'). It doesn't state when not to use the tool or what to do when neither map_id nor request_id is known, 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 already cover the read-only, idempotent, non-destructive profile, and the description adds real value on top: a 200-row-per-call cap, the rows_total field to drive paging, and offset for the next page. It also describes what each rows mode actually contains, which the annotations do not.

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 short but written as one dense run-on with stacked parentheses, so the key facts (default mode, 200-row cap, paging) are buried mid-sentence rather than front-loaded. Every clause is useful; the packaging is the problem.

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 carries the return-value burden and does so: counts, a summary sentence, row lists per mode, rows_total, and paging behavior. Enough remains to call it correctly, though how rows are keyed and whether review mode is costly to compute are unstated.

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

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

Schema coverage is 75%, and the description covers the gap for rows by defining problems/review/all and decoding the candidate sources (github_profile, x_bio, name_search). It also explains the limit cap and offset paging; only import_id is left undocumented in both places, but it is the obvious required key.

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 phrase 'Where an import is: counts, a sentence, and its rows' identifies a status/progress lookup for a single import, distinct from list_imports or run_import. The wording is awkward and never names a sibling, but the verb+resource+payload is decipherable.

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

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

It explains the three row modes and their defaults, which implies the tool is for inspecting an existing import's progress and candidate rows. It never states when to prefer this over list_imports, resolve_import_row, or cancel_import, so routing must be inferred.

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, idempotent, openWorld and non-destructive, yet the description still adds real substance: unknown is 'never a negative', review signals are 'never proof', every claim is traceable to sources with timestamps, and recheck:true performs live GitHub existence checks. That goes meaningfully beyond the structured hints, though output volume/size and latency are not addressed.

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

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

Purpose is front-loaded correctly, but the body is a single sprawling sentence with heavy parenthetical asides that is hard to parse. Every listed field arguably earns its place given there is no output schema, but the structure should be broken into scannable clauses.

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 carries the full burden of describing the return value, and it does so thoroughly — requirements, unknowns, cross-role signals, projects, questions with source links, skill confidence bands, review signals, freshness and sources. An agent has enough to decide and 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 role_id, username, format and recheck are all documented already; the description mostly restates them. It adds only marginal nuance ('format markdown returns text to paste'), which justifies the baseline 3 rather than higher.

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 artifact (role-specific interview brief on one person in a role) and enumerates its contents, so an agent knows exactly what comes back. It implicitly distinguishes itself from analysis siblings by stating it is 'built from what AyHire already saved (free, no new analysis)', but it never names analyze_github_user or enrich_person, so sibling routing is left to inference.

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 'free, no new analysis' implies this is the cheap path versus the analysis/enrich tools, and 'The same person in two roles gets two briefs from the same facts' hints at call pattern. However there is no explicit when-to-use/when-not-to-use statement or named alternative, so usage is only implied.

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

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

The annotations already establish that this is a safe, idempotent read. Beyond that, the description adds substantial behavioral detail: ordering (newest first), inclusion of removed/corrected outcomes with retracted_at and the rule that they never count, plus definitions of current and next. This is rich context an agent would not get 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 front-loaded with the core scope and ordering, then adds only necessary details about retracted outcomes, current/next stages, and role scoping. Every sentence contributes useful information without repetition or filler.

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

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

With no output schema, the description does a good job explaining the returned stages, source attribution, retraction behavior, and current/next semantics. It is nearly complete for a read tool, though the undocumented role_id parameter remains a minor 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 50%: username is documented, but role_id has no schema description. The tool description reinforces that outcomes are scoped to one role and one person, but it does not compensate by explaining role_id format, constraints, or expected values, leaving a meaningful documentation gap.

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

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

The description clearly states the specific resource: one person's hiring outcome history within one role, including the stages and fields returned. It also clarifies the scope boundary that the same person in another role has separate outcomes. It does not explicitly name sibling tools to differentiate from, so it falls 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 implied by the scope: read one person's outcome history in one role. The description does not state when to choose this over alternatives such as get_person_evidence, get_role_funnel, or record_outcome, nor does it provide explicit exclusions.

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

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

Beyond the readOnly/idempotent annotations, it discloses latency (~5 s), cost (free), data source (live GitHub), and the important caveat that `unknown` marks what GitHub could not return and is not a weakness — a real behavioral trait an agent must know before interpreting results. It also explains the compact-vs-full default behavior and what each mode includes.

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 is front-loaded and nearly every clause adds distinct information, but the opening sentence is an extremely long run-on inventory. It remains readable and dense rather than padded, though a short bulleted or segmented structure would scan faster.

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, yet the description enumerates the returned sections, the compact/full difference, the `unknown` convention, and the role_id augmentation. For a broad aggregation tool, an agent has everything needed to call it and interpret the response.

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 100%, and the description still adds meaning: compact means own repos only with forks counted and shorter lists, 'full' means everything, and role_id pulls in the repos the role's search found them through, usable even before the person is added. Only `username` gets no added semantics, which is reasonable given how obvious it is.

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+resource ('read the evidence about a developer') and enumerates the exact contents: profile/README, repos, commits, contribution graph, PRs to other repos, orgs, monthly activity. It explicitly separates itself from read_readme, list_pull_requests, and list_commits, so an agent can route correctly without opening a schema.

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

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

It states the intended use ('check a claim or judge fit yourself') and names concrete alternatives with the condition that selects them: 'Whole READMEs: read_readme. All PRs or commits: list_pull_requests, list_commits.' That is explicit when-to-use plus when-to-use-something-else.

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?

Far beyond the annotations: it discloses that first reads may return state=pending and must be retried with the same arguments after retry_after_sec, that revision.known is false because DeepWiki omits the commit, that text is provider_generated and secondary evidence, that the call is free, and that returned text is data not instructions. These are exactly the operational and trust caveats annotations cannot express.

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

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

Front-loaded with what you get, then caveats and failure modes; nearly every clause carries information. It is dense and long for a two-parameter tool, and the retry instruction introduces an argument name (retry_after_sec) that isn't a parameter, which is a small structure snag.

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

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

No output schema exists, and the description compensates fully by describing the response shape (topic map, one page, cited files with exists_now/not_found_now), the state/pending protocol, the fallback payload, and the revision.known limitation. An agent can call it and interpret the result without guessing.

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 still adds value by explaining the topic selector's semantics (id like '4.1' or title from `topics`, defaulting to the overview page) and by explaining that cited files are checked against the default branch today. It does not clarify the `repo` format beyond the schema, so not 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?

States a specific verb and resource — what a repo's DeepWiki wiki says — and enumerates exactly what comes back (topic map plus one named page plus cited files with existence checks). It is immediately distinguishable from nearby tools like read_readme, ask_repository_question, and contribution_profile.

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

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

Gives an explicit use case ('understand a codebase before judging work in it'), an explicit boundary ('never treat it as proof of who wrote anything — contribution_profile shows that'), and an explicit failure path (fall back to README and GitHub facts when DeepWiki has no wiki). Alternatives and exclusions are both named.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, but the description adds genuinely new behavioral facts: it never contacts the provider and never incurs spend, and the cost field distinguishes settled, in-flight and unknown. What is missing is behavior on failure (unknown job_id, or neither identifier supplied).

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

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

Two dense sentences with the free/read-only guarantee front-loaded and the routing hint last; nothing is redundant or repeated from the 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?

With no output schema, the description carries the return-value burden and does it well by listing state, steps, results, cost and next action. It stops short of explaining what happens when neither job_id nor request_id is provided, which is a real gap for a 0-required-param 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 only 33% — job_id and request_id have no descriptions — and the description only says "by job_id or request_id", which hints that either key works but never states that at least one is effectively required (required list is empty). It compensates partially, not fully, 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 concrete resource (a research job) and enumerates exactly what is returned: state, steps, results so far, cost breakdown and next action, plus the two lookup keys. It names the sibling (start_research_job) used to advance a job, so it is distinguishable from the surrounding research tools at a glance.

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?

"to go on with a job, call start_research_job with its request_id" gives an explicit alternative plus the condition that selects it. It does not cover the other adjacent case (cancel_research_job) or whether this is meant to be polled repeatedly, so it falls short of full when/when-not coverage.

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

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

Annotations already cover readOnly/idempotent/non-destructive; the description goes well beyond by explaining the ranking model, what ranking_basis means, the per-person payload contents, and the concrete truncation rule (up to 2 links per verdict, at most 25 people not looked at yet in compact mode). That is real behavioral context an agent cannot get from 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 ranked-result structure, then usage, then detail-mode caveats; every clause carries information. It is a dense single block that could be split for scanability, but 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?

No output schema exists, so the description carries the return-shape burden and does so fully: headline, one-line why, one thing to check, per-criterion verdicts with links, decision, notes, availability, total score, ranking_basis. An agent can predict the response well 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?

Schema coverage is 100%, so baseline is 3; the description still adds value by explaining what 'compact' actually costs (shorter reasons, fewer links, capped not-yet-looked-at people) versus detail: 'full'. The include parameter's picks/all behavior is left entirely to the schema, which keeps this from 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?

States a specific verb+resource (get a role with everyone in it, ranked) and spells out the ordering semantics (picks, set aside, not looked at yet). The line 'This is the final order: call it after scoring' distinguishes it from upstream siblings like score_role_person or find_people_for_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?

Explicit sequencing guidance ('call it after scoring') and a concrete use case ('who should I talk to first?'). It does not name what to use instead for a lighter/preview read (e.g. get_shortlist), so no explicit exclusion is given.

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

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

Annotations already establish read-only, idempotent, closed-world and non-destructive, and the description goes well beyond them: dedup rules ('each person once per stage; corrections and repeats never count twice'), the crucial 'waiting is not the same as zero' distinction, null rates when the denominator is empty, decline attribution, and approximation caveats for roles saved before outcomes existed. The only shortfall is that the shape of the returned object is described piecemeal rather than as a coherent structure.

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 in the first clause and almost every clause carries real information (definitions, caveats, null handling). It is packed into one long sentence with heavy parentheticals, which makes it dense to parse and slightly buries the operation-level summary.

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 must explain what comes back, and it does so stage-by-stage: reached, waiting, conversions with denominators, declines, interview conversion, time-to-first-shortlist, plus the `lines` narrative and the untracked case. What is missing is an explicit statement of the top-level response structure, but the substance an agent needs to interpret results is present.

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

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

There is a single parameter with 100% schema description coverage ('From list_roles or create_role'), and the description adds no additional meaning about role_id. Baseline 3 is appropriate when the schema fully carries the parameter semantics.

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

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

The opening clause names the resource and the exact stage set (reviewed, shortlisted, contacted, replied, interview, offer, hired), so an agent can tell this is the computed funnel report for a role rather than raw outcome retrieval (get_outcomes) or a shortlist listing (get_shortlist). It never names a sibling explicitly, and the verb is only implied by 'How a role's people moved through', 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?

Usage is only implied: the description makes clear this is analytics over recorded outcomes for one role, and 'tracked false: nobody has recorded outcomes yet' hints at how to read an empty result. There is no explicit when-to-use versus get_outcomes/get_shortlist/get_role, and no prerequisite or exclusion 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 closed-world, so safety is covered. The description adds real behavioral content beyond that: it explains that suggestions are pending-only until set_search_plan is called, that 'every round keeps' required criteria, and the counting rule that people without a location are never counted as in a required place.

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 delivered as one sprawling run-on sentence built from comma-separated noun phrases rather than front-loaded statements. It is dense with useful facts but poorly structured, so an agent must parse it rather than skim it; there is no lead sentence stating the operation.

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

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

There is no output schema, so the description must carry the return payload, and it does so thoroughly across plan content, versions, wider-search states, feedback and rounds. The only notable omission is any explanation of role_id semantics, which is minor for a one-parameter read 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?

There is a single parameter, role_id, with 0% schema description coverage and no explanation in the description beyond the possessive phrase 'A role's search plan'. The meaning is inferable, but the description adds no format, source, or lookup guidance for 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 names a specific resource (a role's search plan) and enumerates its components — required places/languages/words, preferred skills, seed repos, versions, wider searches, feedback, rounds — so an agent knows exactly what comes back. It distinguishes itself from set_search_plan by noting suggestions are never applied without that tool. It lacks an explicit verb up front, but the resource 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?

Usage is only implied: the mention that suggestions 'are never applied without set_search_plan' routes one specific follow-up action to the sibling, but there is no explicit statement of when to call this versus e.g. get_role, next_round, or get_shortlist. The agent must infer that this is the inspection tool for a role's configured 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 cover safety (readOnly, idempotent, non-destructive, closed-world), so the description earns credit for adding ordering ('most recent first'), return content ('AyHire's call and the notes'), and parity with the web app view. It does not mention result limits or pagination, which is the main remaining behavioral gap.

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

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

A single sentence with the resource and scope front-loaded, qualifiers in parentheses, and zero filler. Nothing could be cut without losing meaning.

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, zero-required-parameter listing tool with no output schema, this is nearly complete: it says who is returned, the ordering, and the key fields included. The only omission is whether results are paginated or capped.

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

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

Only one parameter and schema coverage is 100%, so the schema already documents the workspace name/id, the optional default, and the list_workspaces cross-reference. The description reinforces the default ('your current workspace') but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource (everyone shortlisted), the scope (current workspace or a named one, across its roles), and anchors it to a known artifact ('the same list as the web app's Shortlist'). That anchor plus the ordering and content details ('most recent first, with AyHire's call and the notes') clearly separates it from search_candidates and find_people_for_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?

Usage is implied rather than stated: the description tells the agent this is the web app's Shortlist view scoped to a workspace, and the schema points to list_workspaces. It never says when to use this versus search_candidates or find_people_for_role, and no exclusions or prerequisites are given.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true. The description adds real value beyond them: hard limits of 200 KB and 500 people, the fact that nothing changes in the role, that a re-sent file returns the same import, and that paid analyses may be triggered. However it doesn't cover permissions/auth needs or how the preview is returned, so against a low annotation bar this is solid but not exhaustive.

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 core action and the non-mutating guarantee lead, and every sentence carries information (limits, preview contents, idempotency). It is dense in semicolons and parentheticals, which slightly slows parsing, but there is no filler to cut.

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 fully accounts for the return: readiness categories, rows already in the role, excluded lines with reasons, and candidate paid analyses. Combined with size limits, idempotency and the follow-up call, an agent has everything needed to invoke it and interpret the result.

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 text and filename already documented there. The description compensates for the gap by detailing the accepted content — GitHub handles, github.com links, LinkedIn /in/ links, optional columns github/linkedin/name/note — and clarifying that names never identify anyone. role_id remains undocumented in both places, keeping it below 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?

States a specific verb and resource — bringing a list of people into a role — and immediately scopes it to file content rather than direct adds, which separates it from add_people_to_role and run_import. The tool's effective contract (preview that changes nothing) is stated up front, so an agent can distinguish it from siblings without opening a schema.

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

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

Gives an explicit workflow: call this, show the preview to the user, then call run_import. It also names resolve_import_row as the path for uncertain LinkedIn rows and says those rows are never added or scored, which is clear when-not guidance. Alternatives and sequencing are both 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 only flag non-read-only, non-idempotent, open-world; the description adds the actual mechanics: an AyHire email is sent, the recipient must sign in with that address to join, the link expires in 7 days, and re-inviting the same address mints a new link (explaining the non-idempotent hint). That is meaningful disclosure beyond structured fields.

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

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

The core action and the ownership restriction are front-loaded, and every sentence carries information. The recipient-flow clause ('sign in with that address and join, then see its roles, picks and shortlist') is slightly padded but still useful for understanding the invite lifecycle.

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

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

No output schema exists, and the description compensates by saying the invite link is returned and how long it lasts. Combined with prerequisites (owned, non-Personal workspace) and the send_email toggle, an agent has everything needed to call this correctly.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds value the schema lacks: the link is returned regardless of send_email, and send_email=false means link-only delivery. The workspace default and role semantics are left to the schema, which already handles them.

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

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

States a specific verb and resource ('Invite a teammate by email into a workspace') plus the ownership scope ('a workspace you own'). This is clearly distinguishable from siblings like add_people_to_role (adding existing members to a role) and list_workspace_members without opening 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?

Gives real usage context: the workspace must be one you own and not the Personal workspace, and 'Pass send_email=false to only get the link' tells the agent how to vary behavior. It stops short of naming a sibling alternative (e.g., add_people_to_role for people already in the workspace), so it's clear context without explicit 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 readOnly, idempotent, non-destructive, and open-world, so the safety profile is covered. The description adds genuine value beyond that: newest-first ordering, 30-per-page pagination, the exact returned fields, co-author extraction, and AI-agent detection. It stops short of describing page-boundary or truncation behavior, which keeps it from a 5.

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

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

The scoping and return-shape information is front-loaded in a single dense sentence, followed by a short usage line and the cost note. Every element earns its place, though the trailing "Free." fragment reads as an afterthought rather than integrated context.

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 correctly compensates by enumerating the returned fields (subject, date, link, co-authors, AI-agent flag) and the ordering. For a 3-parameter read-only list tool with full schema coverage and rich annotations, that is nearly everything an agent needs; only cross-repo/alternative routing 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 explains username, repo format (owner/name or URL), and page numbering. The description's "one repo (theirs or anyone's)" and "30 a page" largely restate the schema rather than adding syntax or edge-case guidance, 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?

States a specific verb (list) and resource (commits) with clear scope: one developer, one repo, either their own or anyone's. It also previews the return fields, so an agent knows exactly what comes back. It doesn't name sibling tools like search_commits or list_pull_requests, so differentiation is inferential rather than 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?

"Use it to see what they did in a project and how they work" gives a positive usage context, and "Free" signals a cost tier that may matter when choosing between tools. However, it never states when not to use it or which sibling (search_commits) to prefer for cross-repo or filtered queries, leaving the agent to infer the boundary.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description adds genuine context: the result is capped at 5 items, ordered newest first, and each entry includes import_id, progress stage, and counts. This is useful behavioral detail an agent cannot get from annotations, though return-shape formatting details are left implicit.

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 zero waste; the scoping constraints and return fields are front-loaded before the usage hint. Every clause earns its place.

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

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

For a simple read-only list tool with no output schema and full annotation coverage, the description covers return contents, ordering, and cap. The one gap is role_id semantics, which is the remaining piece an agent needs before calling reliably.

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 0% and role_id is a bare string with no explanation. The description only implies role_id by saying 'a role's imports' — it does not say what a role_id is, its format, or where to obtain it (e.g., from list_roles), forcing the agent to guess.

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) and resource ('a role's imports') with scope 'last 5, newest first' and enumerates the returned fields (import_id, stage, counts). It is clearly distinguishable from get_import (single import) by the plural/list framing, though it does not name that sibling explicitly.

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

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

'Use it to find an import started in the web app' gives a use case, implying this is the entry point for locating an import to then act on. However, it never names alternatives (get_import, cancel_import, resolve_import_row) or states when NOT to use it, leaving routing partly 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/openWorld/idempotent annotations, it discloses pagination depth (30 a page, up to 10 pages), sort order, the exact fields returned, and that it runs on GitHub's search with roughly 30 searches/minute. The cost and rate-limit disclosure is exactly the kind of context 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?

Three sentences, front-loaded with the resource and ordering, then filtering, then cost. Slightly redundant where it repeats the page size and state values already in the schema, but nothing is wasted overall.

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 compensates by listing the returned fields, and it covers pagination limits, sort order, filtering, and rate limits. An agent has everything needed to call this correctly and interpret the response.

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 all four parameters are documented there, including the repo format and state enum. The description mostly restates those same constraints ('owner/name', open/closed/merged, 30 a page) rather than adding new semantics, so the baseline 3 applies.

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

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

The description opens with a specific verb+resource ('Pull requests a developer opened') and immediately fixes scope and ordering ('newest first, 30 a page'). The enumeration of returned fields plus the note about 'projects they don't own' makes it clearly distinguishable from the commit-listing siblings.

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

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

It gives an explicit use case ('see what they actually changed in projects they don't own') and states the two narrowing options (repo, state). It stops short of naming an alternative sibling (e.g. list_commits vs this) or stating 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 declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful specifics beyond that: roles are returned newest first and each includes counts of picks, set aside, not looked at yet, and shortlisted.

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

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

A single, front-loaded sentence that states scope, ordering, and return content with no wasted words.

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

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

For a read-only list tool with annotations covering safety and a fully documented optional parameter, the description supplies the key behavioral detail an agent needs: ordering and the aggregate counts included per role. No output schema is needed because the return content is described.

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 workspace parameter has 100% schema description coverage, including its optional default and a pointer to list_workspaces. The description references the workspace option but adds no semantics beyond what the schema already provides.

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

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

The description clearly identifies the resource (roles/open positions) and its scope (current workspace or specified workspace), plus ordering and returned counts. It does not explicitly differentiate from sibling tools like get_role or list_workspaces, 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?

Usage is implied: list roles in the current workspace or a named workspace. The schema points to list_workspaces for workspace discovery, but the description offers no explicit when-to-use or when-not-to-use guidance versus get_role or other 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 establish that this is a safe, read-only, idempotent operation, and the description adds useful behavioral context: freshness via 'when AyHire last checked', provenance for may_fit ('no model, never location'), return content, and the 'added' flag semantics. Pagination, auth, and result-size behavior are not described.

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 purpose and then provides the key return-value semantics without filler. Two sentences carry all necessary information efficiently.

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

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

For a one-parameter, read-only listing tool with rich annotations and no output schema, the description is complete enough: it explains what is returned, what may_fit means, what 'added' signifies, and where to go for the add action.

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

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

Schema description coverage is 100%, and the single optional workspace parameter is already documented in the schema. The description reinforces its default/current-workspace behavior but adds no syntax or format detail beyond the schema.

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

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

The description gives a specific verb/resource combination: it lists everyone watched in the current workspace and explains exactly what the response includes. It also distinguishes adding people by pointing to add_people_to_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?

Usage is clear from the workspace-scoped 'watched' framing, and the description explicitly routes adding someone to add_people_to_role. It does not exclude or compare against nearby read tools such as list_workspace_members, so it falls short of full alternative 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 this as a read-only, idempotent, closed-world operation, and the description adds genuinely new behavior: results are scoped to the current workspace unless one is passed, roles are constrained to owner/member, and pending invites appear only when the caller owns the workspace. It stops short of noting pagination or result ordering.

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

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

A single front-loaded sentence that carries the scope first and then the conditional invite detail, with no filler. The parenthetical aside is slightly awkward but costs little.

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 must carry the return shape, and it only sketches it: members plus roles plus conditional invites, with no indication of structure, ordering, or how invitations are represented. Adequate for a simple read tool but leaves the response format under-specified.

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 explains the optional workspace name-or-id with its default. The description's '(or `workspace`)' only gestures at the parameter without adding format or fallback detail 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 sentence names the resource (workspace members) and specifies what is returned: each person's role (owner or member) and, conditionally, open invites. It implicitly distinguishes itself from list_workspaces and whoami by scoping to a single workspace's membership, though it never states the verb 'list' 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?

There is no guidance on when to choose this over sibling tools such as list_workspaces, whoami, or find_people_for_role. The only routing hint, 'See list_workspaces', lives in the schema rather than the description, so an agent gets no explicit usage conditions here.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description is free to spend its words on domain semantics. It does that well: one workspace per company, shared with that company's team, a guaranteed personal workspace, and the waiting_to_join field for pending join requests — all context an agent cannot get from structured fields.

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

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

Front-loads what the tool returns and which workspace is current, then layers background in descending importance. It is dense but every clause carries information; only the 'shared with that company's team' clause is arguably decorative.

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 input params, no output schema, and a fully covered read-only annotation profile, this description fills both remaining gaps: the domain model and the shape of the returned data (company domain, logo, waiting_to_join). The only omission is an explicit pointer to switch_workspace as the follow-on action.

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?

Zero parameters, so the baseline is 4. The description adds no parameter guidance because none is needed.

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

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

"Your AyHire workspaces and which one is current" states the resource and the scope (the caller's own workspaces, one flagged current), which distinguishes it from list_workspace_members and from switch_workspace. It is phrased as a noun clause rather than a verb+resource, 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?

Usage is only implied: knowing which workspace is current is obviously a precondition for switch_workspace, but that sibling is never named, nor are create_workspace or invite_to_workspace excluded. An agent can infer the context but gets no explicit 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 say readOnlyHint=false but the description explains exactly what is written ('saves only people the role has not seen') and that the call is free, unscored, and resumable from the last round. The request_id retry clause reconciles the idempotentHint=false annotation by explaining that idempotency is opt-in via request_id rather than default. This is materially more than the annotations convey.

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

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

Front-loaded with the core action, then the exhaustion path, then cost/retry caveats — a sensible ordering. The prose is a single dense run-on with stacked parentheticals, which costs some readability, though nearly every clause carries unique 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 no output schema, the description still covers the key return signals (round.changes, round.exhausted, the broaden suggestions) and the empty-result semantics, which is the critical part for an agent. It stops short of describing the shape of the returned people list, but that gap is minor relative to what it does disclose.

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 50%, with only request_id documented in the schema; the description reinforces its retry semantics and adds the intent behind it. role_id is only implied by 'a role's plan' and never explicitly defined, which is the one 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 ('Run the next round of a role's plan') and immediately disambiguates it from the search/plan siblings by describing the resumable, plan-driven behavior. An agent can tell this apart from find_people_for_role, search_people, and set_search_plan without opening a schema.

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

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

Explicit preconditions ('Needs a plan (create_role makes one)'), explicit routing for the terminal case ('suggest a wider search from broaden ... approve one with set_search_plan'), and explicit follow-up ('call score_role_person for the people worth it'). It also states the retry protocol with request_id, 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 declare readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered. The description earns credit by adding behavior beyond that: the 30,000-character truncation ceiling with a 'truncated=true' signal and the fact that it is free. It stops short of describing error behavior for missing READMEs.

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: the resource and its size limit come first, then the usage rationale. No filler, no repetition of the title 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?

For a one-parameter read tool with a rich annotation set and no output schema, the description covers what is returned (whole README plus link), the size cap and truncation signal, and the cost. Minor gap: no mention of what happens when a repo has no README or how errors surface.

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

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

Schema coverage is 100% for the single 'repo' parameter, including the owner/name-or-URL format and an example. 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?

States a specific verb and resource ('The whole README of any public GitHub repo') plus explicit scope limits (public only, 30,000 character cap). This is clearly distinguishable from siblings like search_repos or list_commits, which operate on different resources.

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 line 'Read the work itself before you judge it: what the project does, how serious it is, how well it is explained' gives a clear situational trigger for when this tool is the right choice. It does not, however, name an explicit alternative or state when not to use it.

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

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

Despite annotations covering mutation/idempotency, the description adds substantial context: workspace-wide sharing, source attribution defaults (automated vs human), dedup behavior returning already: true, stage side effects (shortlisted also shortlists, contacted sets contacted date), and the fact that replaces removes the old outcome but keeps it in history. The last point usefully qualifies destructiveHint=false by explaining what is actually lost.

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 but front-loaded: what to record first, then guardrails, then effects, then corrections, then defaults. Every sentence carries a distinct fact and none repeat structured fields verbatim.

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

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

Even without an output schema, the description covers the important return behavior (already: true on repeats), mutation side effects, attribution, and correction flow. An agent has everything needed 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?

At 71% schema coverage, the description still adds meaning beyond the schema: the side effects of specific stage values, the semantics of replaces (an active outcome of theirs in this role, sourced from get_outcomes), the default for happened_at, and the human-vs-automated distinction for source.

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 ('Record what happened with someone in a role') and enumerates the exact value space of outcomes. It is clearly distinguishable from siblings like decide (which it names as an equivalent for the shortlist side effect), remove_outcome, and get_outcomes.

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 usage constraint ('Only record what the user tells you happened, never a guess'), names the alternative tool for corrections ('pass its id as replaces (from get_outcomes)'), and tells the agent that shortlisted is equivalent to decide for that sub-action.

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?

Adds substantial behavior beyond annotations: it is a soft delete that stays in history marked removed, never counts, and can be recorded again. It also discloses side effects for shortlist/contacted outcomes and the idempotent already:true result, directly complementing idempotentHint and clarifying why destructiveHint is false.

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 core purpose and precondition are front-loaded in the first sentence. The remaining clauses are dense but each carries behavioral value; the description is slightly long but not padded.

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

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

This is a mutation tool with no output schema, yet the description explains the soft-delete lifecycle, special cases for shortlist/contacted outcomes, and repeat-call behavior. Combined with annotations, an agent has everything needed to call it correctly.

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

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

Schema coverage is 67%, and the description reinforces outcome_id's source (get_outcomes) and explains the role/username relationship. role_id is still only indirectly characterized as 'in a role,' but the description meaningfully supplements the schema rather than merely repeating it.

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

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

States a specific verb (Remove), resource (outcome in a role), and identifier source (id from get_outcomes), which clearly distinguishes it from record_outcome and decide. An agent can identify the operation 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?

Gives an explicit trigger: 'when the user says it was recorded by mistake.' It also clarifies alternative semantics for shortlist removal (same as decide none) and contacted removal, so the agent knows when this tool is and is not the right choice.

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

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

Beyond the annotations, the description adds crucial behavior: free/read-only is reinforced, failures list unreadable sources, multiple or zero results are normal, and returned text is data not instructions. This is rich context that materially helps an agent interpret results safely.

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 front-loads the core purpose and every sentence carries operational meaning. It is longer than average but not padded; the evidence rules and caveats are compressed into a single paragraph.

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

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

For a tool with no output schema and non-trivial evidence logic, the description covers return semantics (several or none, failures) and safety (data not instructions). Combined with annotations, an agent has everything needed to call and interpret 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 coverage is 100%, so the baseline is 3. The description adds useful meaning: name alone never resolves, github_orgs are checked like any other, and domain drives resolution. This goes beyond the schema descriptions and clarifies how parameters interact.

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 a company's official GitHub organizations from its domain, with a clear explanation of the reciprocal-evidence rule. It distinguishes itself from start_company_map by noting when LinkedIn data is tied and how github_orgs triggers scanning.

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

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

Explains what counts as confirmed vs a likely candidate and how github_orgs is used, giving clear operational context. It does not explicitly enumerate when to prefer this over every sibling, but the evidence rules and the start_company_map reference provide meaningful 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 mutating-but-non-destructive, idempotent, closed-world behavior, but the description adds non-obvious traits: github_username is not applied immediately but 'added on the next run_import', linkedin_list adds to the role's list 'without a GitHub account', and an existing handle makes the row 'a duplicate'. These deferred-effect and validation rules are exactly the behavioral context the annotations don't 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?

It is a single front-loaded sentence that leads with the key constraint and then branches. Every clause carries information, though the nested parentheticals make it dense and somewhat run-on to parse in one pass.

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

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

For a 4-param mutating tool with no output schema, the description covers the important behaviors: branch semantics, deferred application, and duplicate detection. Missing only an explanation of import_id and any note on the response/error outcome, which keeps it from being fully complete.

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

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

Schema coverage is only 50%, so the description must compensate, and it does for the hard part: it explains what each action enum value does (skip vs linkedin_list) and what github_username triggers downstream. import_id remains undocumented in both schema and description, keeping this below 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 clearly establishes that this tool resolves/confirms the identity of an imported row, and it enumerates the three resolution branches (github_username, action=skip, action=linkedin_list). It distinguishes itself from run_import ('added on the next run_import') and from get_import ('row number, from get_import'). The wording 'Say who a row to check is' is slightly awkward but the resource and action are 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?

Strong contextual constraint: 'only once the user decided (never guess, never by name)' tells the agent exactly when to call and what not to do. The three alternative actions and their consequences are spelled out. It stops short of explicitly naming which sibling (get_import vs run_import) to invoke before/after, leaving some sequencing 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 declare a non-read-only, idempotent, non-destructive write; the description adds value beyond that by disclosing that decisions are audited, workspace-private, and persist into later maps, plus what 'reset' actually restores. It omits permission requirements and failure behavior for invalid map_id/match_id pairs.

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

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

Three sentences, zero filler: the action and its enum semantics come first, the guardrail second, and the side effects last. The parenthetical glosses are the densest part but each removes ambiguity rather than adding bulk.

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 5-parameter mutation with no output schema, the description covers the important ground: what each decision means, the consent requirement, and the persistence/audit consequences. Missing only return-value shape and error/validation behavior, which is a modest gap given the rich semantics already provided.

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?

At 60% schema coverage, the description carries real weight by defining the three decision enum values semantically (same person / not same person / back to evidence-only), which the schema's bare enum does not. It does not clarify map_id or note, both of which also lack 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 names a specific verb (record the user's decision) and a precisely scoped resource (a possible GitHub-account/LinkedIn-profile match inside a company map), and it spells out the three decision values. It stops short of naming a sibling such as get_company_map or decide to route the agent, so it is clear rather than fully differentiating.

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?

'Only on the user's word, never your own guess' is a concrete when-to-use constraint that excludes the main failure mode (agent inferring a decision). It gives no positive workflow guidance, e.g. that evidence should be reviewed via get_person_evidence or the map's matches section first, and names no alternatives.

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

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

The description adds substantial behavior beyond the annotations: one bounded step per call, up to 25 people per step, continuation semantics, paused/resume handling, hourly analysis limits, and skipped rows. These details are important for a non-readonly, non-idempotent mutation tool and do 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 dense but front-loaded, starting with the core action and then layering in continuation, pause, analysis, and no-op conditions. Every sentence carries useful operational meaning 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 mutation behavior, lack of output schema, and stepwise import semantics, the description is complete enough to invoke and continue the tool correctly. It covers the key state signals (`more`, `resume_at`, `busy`) and analysis-limit behavior.

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 `analyze` parameter is explained well, including first-call-only behavior and hourly analysis limits. However, `import_id` is undocumented in both the schema and the description, leaving half of the parameters without added semantic guidance.

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: start or continue an import in bounded steps. It clearly scopes the operation to post-preview use and continuation, but it does not explicitly name sibling tools such as get_import, cancel_import, or import_people for 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?

It gives explicit conditions for use: after the user has seen the preview, call again while `more` is true, and resume after `resume_at` when paused. It also states that `busy=true` means another step was running and the call did nothing.

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 openWorldHint, so the safety profile is covered. The description adds genuinely non-obvious behavior: a fresh saved result is reused, otherwise it scrapes live, and the refresh flag overrides the cache. It stops short of noting latency or rate-limit implications of scraping.

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

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

Three tight sentences with no filler. Structure is slightly inverted — the first sentence is about the sibling tool rather than front-loading what this tool does, forcing the reader to reach sentence two for the core purpose.

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

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

For a 2-parameter read-only tool with full schema coverage and rich annotations, the description covers persistence, caching and routing. With no output schema, a hint about what a 'score' actually contains would close the remaining gap.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description reinforces refresh semantics by explaining the cache-freshness logic that gives the flag meaning, but adds no format or constraint detail beyond the schema.

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

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

The description conveys a specific verb+resource (scrape and score a GitHub developer) and pins down the key differentiator: it never writes to the database, unlike analyze_github_user. It also explicitly separates itself from score_role_person, though the opening sentence leads with the sibling rather than stating this tool's own purpose first.

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?

Explicit routing: 'For someone in a role, use score_role_person instead' names the alternative and the condition that selects it. It also implicitly defines when to pick this over analyze_github_user — when you want a lightweight, non-persisting score.

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?

Adds substantial behavior beyond annotations: discloses data sources (own repos, work on others' projects, role search repos), timing and rate-limit behavior, saved-vs-new analysis cost, timeout retry semantics, ranking instability, and that someone not yet in the role is added first with reason. These are exactly the operational details an agent needs.

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 main action and then layers in scope, cost, ranking behavior, and timeout handling without filler. Although dense, every clause carries actionable information for selecting or invoking the tool.

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

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

Covers the complex mutation-like behavior, external reads, timing, rate limits, ranking effects, and retry behavior despite having no output schema. The return value is summarized as AyHire's call and place among picks, though the exact response shape is not detailed; still, the description is largely complete for correct use.

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 description adds useful meaning for reason (kept when the person is added now) and implies role_id determines criteria and ranking. It does not further document role_id formatting, but username is already described in the schema and the lifecycle of reason is clarified.

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 multi-step action: analyze one person, judge them against the role's criteria, check availability, and return them with AyHire's call and ranking. It clearly scopes the tool to a single person within a role, distinguishing it from bulk search/find 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?

Gives clear usage context: score people worth it because new analyses cost 15-25 seconds and count toward the hourly limit, while saved analyses are free and instant. It also says to call get_role for the final ranking and to retry once after a timeout. It does not explicitly compare to sibling score_candidate, but otherwise guidance is strong.

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, closed-world), and the description adds non-obvious behavioral context: results are restricted to the previously analyzed corpus and are ranked by similarity plus score. It leaves the meaning of the score and the result shape unexplained, which keeps it from a 5.

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

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

Two compact sentences with the capability, mechanism, an example, and the constraint front-loaded before the alternative. Every clause carries information; no filler.

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

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

There is no output schema, and the description does not describe what a result contains (person fields, score, evidence) or how the similarity/score ranking blends together. Combined with completely undocumented nested filter fields, the definition is usable but leaves real gaps 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 75%, below the threshold where the schema alone suffices, and the undocumented part is the entire nested `filters` object (org, company, category, languages, min_stars) — the most semantically ambiguous parameter. The description says nothing about filters, does not explain the interaction between `threshold` and ranking, and only restates 'plain-language' for query, which the schema already says.

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

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

States a specific verb and resource ('Plain-language search over developers AyHire has already analyzed'), plus the ranking mechanism (semantic similarity plus score ranking) and a concrete example query. This clearly separates it from siblings like search_people or find_people_for_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?

Explicitly states the limitation 'Only finds people analyzed before' and routes the agent to analyze_github_user when the person is missing — a genuine when/when-not with an alternative. It does not, however, distinguish itself from the similarly named search_people, which an agent could easily confuse with 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?

Extremely informative beyond the annotations: forks are skipped but counted as in_forks unless a repo is named, unlinked-email commits are only counted as unattributed, results are grouped with up to 3 examples each, and the rate limit (~30/min) and cost ('Free') are disclosed. The role_id side effects — search logged in role history and returned people marked as seen — explain why readOnlyHint is false, keeping the description consistent 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?

One dense paragraph with the core purpose and output shape front-loaded, and every sentence carries operational detail. It is somewhat run-on in the middle (fork/unattributed/role rules piled together), 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?

There is no output schema, yet the description specifies the return shape (people grouped, ordered by match count, with repo, subject, UTC day, link and repo-count per person). Combined with rate limits and pagination, an agent has everything needed to call and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: naming a repo changes fork-handling behavior, and role_id/include_seen jointly control exclusion of already-seen people. Page size (100 commits) is left to the schema, so it is not a full 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?

States a specific verb and resource — 'Find who actually wrote commits matching some words' — and immediately distinguishes itself from raw commit-listing siblings by describing person-grouped output. An agent can tell this is a person-discovery tool over commit text, not a commit listing or a repository 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?

Gives concrete query examples ('smartlead webhook', 'hubspot sync') and a clear use-case framing: 'Good for finding practitioners whose work is spread over many small repos.' It also explains the two operating modes (scoped by repo/org vs. role-scoped with exclusion of seen people). It stops short of naming sibling alternatives like list_commits or search_people, so it falls just below 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?

Adds real behavioral context beyond the annotations: what each result contains (bio, location, company, followers, hireable, top 3 repos), that the exact query and total are returned, cursor pagination via next_cursor, and that the call is free. It also explains the non-read-only side effect (role_id logs the search and marks people seen), which reconciles with readOnlyHint=false. Slightly short of 5 only because rate/limit behavior is left to the schema.

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

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

Front-loaded with the core matching semantics and alternative routing, with zero filler sentences. It is a dense single paragraph rather than cleanly segmented, which makes it slightly harder to scan for a 10-parameter tool.

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

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

No output schema exists, yet the description covers return contents, the echoed query, total, and pagination cursor usage. Combined with the role_id side-effect explanation, an agent has everything needed to call this correctly.

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

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

Schema coverage is already 80%, but the description adds genuine meaning: query words must all match GitHub-side so keep it to one to three, location may be a region with a top-100 read, and role_id excludes already-seen people unless include_seen. That goes beyond the field-level schema text.

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 GitHub profiles) and immediately defines the matching surface: name, login and bio. It also explicitly contrasts itself with find_people_behind_repos and search_candidates, so an agent can route between them without reading schemas.

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

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

Gives concrete when-to-use guidance ('roles where profiles say more than repos', 'a location constraint') and names the alternative plus the condition that selects it ('for engineers, mining the contributors of seed repos ... is often stronger'). This is explicit routing, not 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/open-world/idempotent, so the description's job is incremental – and it delivers: page size of 30, result fields returned (description, stars, topics, owner type, dates), the exact-query echo, no star floor by default, and 'Free'. It stops short of stating rate limits or total-result caps beyond the 10-page ceiling.

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?

Capability and result shape are front-loaded, with usage and query-strategy advice following. It is a single dense run of clauses; splitting the strategy tips from the capability statement would improve scanability, but no sentence is 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?

No output schema exists, yet the description enumerates the returned fields and pagination behavior, and all 9 optional parameters are covered by a high-coverage schema. An agent has everything needed to call it correctly and interpret the result.

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 89%, yet the description still adds real meaning: AND semantics for query ('every word must match, so use few'), the default sort of stars, and the absence of a star floor. That goes beyond the schema's per-field text rather than repeating it.

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

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

States a specific verb (search) plus resource (GitHub repositories) and enumerates the filter axes (words, topic, language, owner org, stars, dates) and ordering. It is clearly distinguishable from siblings like search_people or analyze_github_user, and it names find_people_behind_repos as the natural follow-on.

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 (seed lists, role-relevant projects, small serious repos with no star floor) plus an explicit alternative heuristic: 'Topic searches are usually cleaner than keywords'. It also specifies the chaining step to find_people_behind_repos(repo=...), so an agent knows both when to pick it and what to do next.

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 destructiveHint=true and idempotentHint=true; the description adds the concrete consequence of the destructive replace, namely that existing judgements become stale until score_role_person runs again. It also discloses that the web app mirrors these criteria, which is context the annotations cannot carry. It doesn't cover the 8-item cap or permission requirements.

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

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

Three sentences, front-loaded with the mutation, then the authoring rule, then the downstream consequence. No filler; the example earns its space by making 'specific beats generic' concrete.

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

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

No output schema exists, and the description covers what gets written, how to phrase it, and what happens to dependent scores afterward. Missing only the item-count limit and any permission prerequisite for a destructive, role-wide rewrite.

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 50% and the criteria array is already richly documented in-schema; the description adds emphasis on writing specific, user-voiced criteria with a contrastive example. role_id remains undocumented in both places, so the description does not fully compensate 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 ('Replace a role's criteria') and defines the criteria model (need + importance) without opening the schema. It does not distinguish itself from the close sibling suggest_role_criteria, so an agent must infer the difference between generating and persisting criteria.

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 usage through 'Use the user's words; specific beats generic' and by noting people become out of date until score_role_person re-judges them, which is real workflow guidance. It never states when to prefer this over suggest_role_criteria or when not to replace existing 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?

Adds substantial behavior beyond annotations: every version is kept, restore_version reverts, omitted fields stay unchanged (confirming the idempotent merge semantics), and it returns the plan plus a diff. No permissions/auth context, but the mutation profile is well covered.

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

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

Front-loaded with the action and versioning model, and every clause carries usable information. The middle section is a dense run-on list of field meanings that takes effort to parse but wastes little.

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 9-parameter tool with a nested object, it covers what changes, merge semantics, concurrency safety, and the return value ('the plan and what changed'), which stands in for the missing output schema. Auth/permission requirements are the notable omission.

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

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

Schema coverage is only 56%, yet the description explains the meaning of nearly every parameter – required (places/languages/terms with 'words someone's work must show'), preferred ('skills that move people up'), seeds ('owner/repo whose people each round reads'), location_unknown default, approve/reject, version, and restore_version. It compensates for the gaps, e.g. giving `preferred` semantics the schema omits entirely.

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 ('Change what a role's rounds keep to and look for, as a new version of its plan') and immediately clarifies the versioning model. An agent can distinguish it from get_search_plan, though differentiation from the sibling set_role_criteria is left implicit.

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

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

Gives concrete context: pass version so concurrent changes aren't overwritten, use approve/reject with ids from get_search_plan, and a constraint ('Only change required constraints when the user asks'). No explicit when-not-to-use beyond that, so not 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?

Goes well beyond the annotations (readOnlyHint=false, idempotent) by disclosing runtime (~30 s per call), idempotent resume semantics with no double charge, the $0.50 research cap, coverage/limits reporting, namesake holding (linkedin_name_only), evidence-linking rules, and a prompt-injection warning. These are traits an agent cannot get from the structured fields.

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

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

Content is dense but delivered as one unbroken paragraph with long run-on sentences, so critical operational guidance (next_action.code, paid consent gate) is buried near the end. Little is wasteful, but the lack of structure hurts scannability.

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 10-parameter, no-output-schema, open-world tool this covers most of what's needed: cost, resume, limits, identity-linking confidence tiers, and failure/next-step codes. It stops short of describing the shape of the returned map (github vs linkedin vs coverage sections), which an agent must infer.

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

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

Schema coverage is already 90%, but the description still adds semantics: max_cost_usd switches on the paid side, request_id is the resume key, github_orgs are 'checked, never trusted', and limits explain the coverage cuts. Minor gap: it doesn't tie limits fields to default behavior as the schema does.

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: it maps a company's public engineering ecosystem across named sources (official GitHub orgs via resolve_company, public members, repo contributors, GitHub company field, optional LinkedIn people). An agent can tell what it produces and how it differs from resolve_company and review_identity_match, which are named in 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?

Gives explicit conditional guidance: the paid LinkedIn side runs only with max_cost_usd and the user's consent, the same request_id resumes rather than re-bills, and the agent is told to branch on next_action.code. It never explicitly contrasts with the sibling get_company_map or find_people_behind_repos, so retrieval-vs-start selection is left to inference.

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

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

Adds substantial behavior beyond annotations: it is paid, server-capped at $0.50 default, idempotent because each paid call is persisted by key before sending, runs ~40s of steps, budget can be raised on later calls, and result data carries integrity caveats ('what LinkedIn says, not confirmed employment... never a complete list'). The 'Paid' framing is consistent with readOnlyHint=false and the 'never pays twice' with idempotentHint=true.

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

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

Front-loaded with 'Paid. Starts a research job...' and every detail is substantive. However, sentences are long and parenthetical-heavy, and the trailing cost sentence ('settled, in flight and unknown are kept apart') reads as grafted-on, hurting scannability.

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

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

No output schema exists, so the description carries the burden — and it does: it documents the next_action.code state machine, cost-bucket semantics, budget behavior, result caveats, and the give_company_id recovery path. Complete for a complex, stateful, paid 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?

Adds meaning beyond the 67%-coverage schema: max_cost_usd is the user's per-job authorization and raising it later lifts the budget; without workspace the job is located in whichever workspace it started; kind=company_people is explained including fidelity caveats. These are genuine semantics the schema does not provide.

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 ('Starts a research job, or resumes the one with this request_id') and clarifies it is the paid, stateful entry point, distinct from siblings like get_research_job and cancel_research_job. An agent can identify it 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?

Gives explicit when-to-call guidance: reuse the same request_id to resume without paying twice, and call again per next_action.code (call_again, wait_until, give_company_id, raise_budget). It doesn't explicitly name sibling alternatives (e.g. get_research_job for status), so just short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds important context beyond annotations: suggestions are not persisted, must be shown to the user, and are intended to be saved later via set_role_criteria. It does not describe the return shape or any operational limits, which keeps it from a 5.

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

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

The description is compact and front-loaded with the core action. Every clause earns its place by adding purpose, persistence behavior, or the follow-up workflow.

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, one-parameter tool with annotations covering safety, the description provides enough to call it correctly: what it does, when to use it, and what to do with the result. It is slightly incomplete because it does not explain the return format and only indirectly clarifies role_id semantics.

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 0% for the single parameter role_id. The description implies that role_id identifies the role whose title and brief are used, adding some meaning, but it does not explicitly name the parameter or state that it must reference an existing role. This partially compensates for the schema gap but not fully.

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: 'Suggest criteria for a role from its title and brief.' The phrase 'without saving them' directly distinguishes it from the sibling tool set_role_criteria, 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?

Explicitly names the workflow: show suggestions to the user, then save with set_role_criteria if desired. It also gives concrete conditions for use: 'when the brief changed or the current criteria feel off.' This is clear when-to-use guidance with a named alternative.

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

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

Annotations already declare non-readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: the switch persists for both the agent session and the web app, and it changes where role tools subsequently list and create. It stops short of stating any membership/permission prerequisite for switching.

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

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

Three short sentences, front-loaded with the action and its scope, followed by the consequence and the alternative. No filler or restatement of the title.

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

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

For a one-parameter, no-output-schema state-change tool, the description covers effect, scope and the alternative path. The only missing piece is whether the switch requires prior membership or returns a confirmation.

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 already documents `workspace` as a name or id sourced from list_workspaces, so the description adds nothing new about the parameter itself. 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 concrete action and object: make a workspace the current one. It also scopes the effect ('for this agent and the web app'), which distinguishes it cleanly from list_workspaces and create_workspace in the sibling set.

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 alternative path — pass `workspace` to another tool for a single-call override — and gives the condition that selects it. The agent does not have to guess when a full switch is warranted versus a per-call override.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that by explaining the consequence ('Their daily checks stop for this workspace') and confirming the effect is scoped to one workspace rather than global. It doesn't say whether re-watching restores checks or what happens if the person isn't watched.

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

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

Two short sentences with zero filler, and the scope constraint is front-loaded before the effect. Nothing is wasted.

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