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

With readOnly/idempotent/openWorld annotations already covering safety, the description adds real beyond-schema context: the affiliation field can be stale so employment must not be inferred, view='context' drops the nested author record and swaps numeric impact_clusters for impact_directions, server collections cap at 100, and neighbor computation adds significant latency. This is exactly the operational nuance 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 purpose, then the data-quality caveat, then a clearly enumerated view section, then the neighbor flag. Every block is structured and earns its place; it is slightly long but the length is justified by the two response shapes it must disambiguate.

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

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

An output schema exists so return values need not be re-explained, and the description still covers the response-shape differences, caps, and latency. It is complete for correct invocation, missing only explicit sibling routing, which is minor given the output schema and annotations.

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%, so the description must carry the parameters and it largely does: it enumerates both view enum values with distinct semantics and explains what include_neighbors adds along with its latency cost. Only author_id_or_url goes undocumented, but its meaning is self-evident.

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 ('Fetch agent-oriented context for a Lacuna author') and clarifies via the view section that it returns an aggregate context (papers plus impact_directions). However, it never explicitly distinguishes itself from siblings like get_author_papers, get_author_directions, or get_author_neighbors, leaving the agent to infer that this is the composite entry point.

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

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

Provides implied guidance by marking view='context' as 'recommended' and explaining what each mode does. But there is no explicit when-to-use-this-vs-alternatives statement, e.g. when to call get_author_context rather than get_author_papers or get_author_neighbors, which is exactly the ambiguity an agent faces with these siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description's only added behavioral detail is that results are paged ('one page'), which is useful but thin; it says nothing about ordering, total counts, or how paging interacts with offset/limit.

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 with no filler, which is appropriate for a simple list tool. It is efficient, though almost too terse for a tool with an undocumented identifier parameter.

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

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

An output schema exists, so return values need not be described. However, with zero schema description coverage, no sibling differentiation, and no explanation of the required author identifier, the description is only minimally sufficient for correct invocation.

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

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

Schema description coverage is 0% across three parameters, so the description must compensate and largely does not. The phrase 'one page' hints at limit/offset semantics, but the critical author_id_or_url parameter is never explained — no indication of accepted ID format versus URL form.

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: fetching an author's named research directions, scoped to a single page. It is clear what the tool returns, though it never distinguishes itself from close siblings like get_direction or get_direction_papers, which an agent could easily confuse it with.

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 when-to-use guidance at all. Given siblings such as get_direction (single direction) and get_direction_papers (papers within a direction), the description should say when to list an author's directions versus drilling into one, but it leaves that entirely 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, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds that results are ranked and paged, but does not explain how neighbors are computed, whether a missing author errors, or rate limits. Some added context, but thin.

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 with no filler. It is efficient, though its extreme brevity leaves the definition under-specified rather than 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?

An output schema exists so return values need not be explained, but with three undocumented parameters and no usage guidance, an agent cannot confidently supply limit/offset or know what a 'neighbor' is. The definition is incomplete for a paginated, ranked query tool.

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

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

Schema coverage is 0% for all three parameters, so the description must compensate and does not. It never mentions author_id_or_url, limit, or offset, leaving the pagination contract entirely undocumented. Only vague hints ('one ranked page') gesture at limit/offset.

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

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

Clear verb (fetch) plus resource (neighboring/similar authors) and scope (one ranked page). It distinguishes itself from siblings like get_author_papers and get_author_directions by focusing on similar authors, though it never defines what 'neighboring' authors actually are.

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

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

No guidance on when to use this tool versus other author-related siblings, nor what prerequisite (a valid author id/URL) is needed. The word 'page' implies pagination but no conditions or alternatives are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so safety is fully covered elsewhere. The description contributes the ordering behavior (newest to oldest) and that results are paged, which is genuine but modest added context; it says nothing about pagination mechanics or the open-world nature of author resolution.

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 conveys resource, paging scope, and ordering with no filler or redundancy.

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

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

An output schema exists, so return values need not be described. However, for a tool with three undocumented parameters, the description only covers ordering and the fact of paging; it omits the accepted author identifier format and how to move to subsequent pages, leaving real 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%, so the description must carry parameter meaning, and it largely does not. "One page" gestures at limit/offset but gives no page-size or pagination semantics, and author_id_or_url is never explained even though the name implies it accepts either a raw ID or a URL of differing formats.

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 (fetch) and resource (an author's papers) plus the ordering, which is enough to distinguish it from single-item siblings like get_paper and get_direction_papers. It never names an alternative or explicitly contrasts with them, 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 only implied: the agent can infer you call this to list an author's works, but there is no guidance on when to prefer this over search_lacuna, get_paper, or get_direction_papers, and no stated prerequisites (e.g. an author must already be resolved). No exclusions 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 cover readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context beyond them: the two response shapes, that 'context' is default/recommended, and that 'full' is cheaper for basic metadata. This is useful behavioral detail about output size and cost trade-offs.

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 and input forms, then a bulleted breakdown of view options. Structurally clear, though the parenthetical about context containing full-provided fields is slightly convoluted.

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-param read-only tool with an output schema, the description covers both parameters, the default view, and the response-shape trade-offs. It omits what the output schema already covers, which is appropriate. Minor gap: no mention of error behavior for invalid IDs.

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

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

Schema coverage is 0%, so the description must compensate, and it largely does: it explains the accepted formats for cluster_id_or_url (numeric ID or URL ending in the number) and the view enum semantics with defaults and cost trade-offs. The only gap is that the URL format is not exactly specified.

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 (Fetch) and resource (Lacuna research direction/cluster). It does not explicitly differentiate from siblings like get_hypothesis or get_direction_papers, but the resource noun 'direction/cluster' is distinct enough for an agent to route correctly.

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

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

The description explains the input forms (numeric ID or URL) and the view semantics, implying usage, but never states when to prefer this tool over get_direction_papers or search_lacuna. No exclusions or alternative-routing guidance 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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description goes beyond that by disclosing a real behavioral trait: 'full' returns 'much larger' raw upstream records whose info blobs 'dominate the payload', which helps the agent reason about cost. It stops short of mentioning pagination limits or rate behavior.

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

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

The opening sentence is front-loaded and the two-view breakdown is well structured as a scannable list. The parenthetical enumerations ('openalex/dblp/arxiv ids, etc.') are slightly padded but each clause carries 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?

An output schema exists, so return values need not be explained, and the view description compensates by characterizing the payload shape. What remains thin is pagination mechanics and the alternate URL form of the cluster argument, which are gaps but not blockers for correct invocation.

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

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

Schema description coverage is 0%, so the description carries the burden, and it fully documents the `view` enum with per-value payload tradeoffs. It leaves `page`, `limit`, and `cluster_id_or_url` unexplained beyond the word 'paginated', and notably never says the cluster argument also accepts a URL despite the parameter name. Partial compensation only.

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

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

The description names a specific verb and resource ('Fetch paginated papers associated with a Lacuna research direction/cluster'), which is unambiguous about what comes back. It does not explicitly distinguish itself from siblings like get_direction or get_paper, so the agent must infer the boundary, but the 'papers associated with a direction' framing is clear enough.

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

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

The description gives solid when-to-use guidance for the `view` option ('compact' default/recommended, 'full' only when raw metadata is needed), which is genuinely useful. However it says nothing about when to call this tool versus get_direction, get_paper, or search_lacuna, so the tool-selection guidance 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 already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the "context" view drops the raw upstream record server-side (whose markdown would duplicate summary_markdown), and "full" exposes version history and signal counts with bodies in versions[].markdown. It stops short of describing error behavior for an invalid or unresolvable id/URL.

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 purpose sentence followed by a usage line and a tight bulleted breakdown of the enum. Every sentence earns its place; no restatement of the schema's enum list or boilerplate.

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

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

An output schema exists, so return values needn't be documented, yet the description usefully clarifies the two response shapes and where proposal bodies live. Combined with the annotations and the idempotent read-only profile, an agent has everything needed to invoke 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 description coverage is 0%, so the description must carry the parameter burden. It fully explains the view enum — both values, the default, which is recommended, and the cost/benefit of each — but only implies the format of hypothesis_id_or_url through its name, without stating accepted ID vs URL forms.

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 (Fetch) and resource (a generated ML/AI research proposal) plus the source system, Lacuna. It also positions itself relative to sibling tools by naming search_lacuna with search_type="hypothesis" as the prerequisite step, so an agent can place it in the workflow 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?

Explicitly states when to call it ('Use after search_lacuna(search_type="hypothesis")') and gives per-value guidance for the view parameter, including a when-not ('Use only when you need versions or signals' for "full"). This is the strongest form of routing guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds genuinely new behavioral context beyond that: results are ordered by paper count, and it names the specific response fields used for paging.

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 and front-loaded, opening with the core action and following with ordering and pagination notes. Each sentence carries useful information with no filler.

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

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

Because an output schema exists, return values need not be restated. However, for a tool with three inputs, it omits the meaning/format of institution_key_or_url and does not tie the limit/offset inputs to the described paging behavior, leaving a moderate 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 0%, so the description carries the burden of explaining parameters. It references output fields (authors_offset, authors_truncated) but never documents the input parameters limit or offset, nor the expected format of institution_key_or_url. It fails 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?

The description states a specific verb and resource: 'Fetch one page of authors affiliated with a Lacuna institution.' It clearly communicates the resource scope (institution-affiliated authors), though it does not explicitly contrast with siblings like get_author_papers or get_institution_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?

It gives implied usage via pagination guidance ('page through the complete list'), which signals this is a paged listing tool. However, there is no explicit when-to-use/when-not statement or routing to alternatives such as get_institution_context or get_author_papers.

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, openWorld, and non-destructive, so the safety profile is covered. The description adds genuine behavioral detail beyond that: the compact view drops the duplicated institution block server-side, and the full view exposes explicit truncation metadata — useful for reasoning about response size and completeness.

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 a clean bulleted breakdown of the view values, closing with the sibling pointer. The prose is a bit exposition-heavy in the two bullets but every sentence carries actionable information.

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

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

An output schema exists, so return values needn't be spelled out, yet the description still characterizes each response shape well. The only real gap is the undocumented institution identifier parameter, which the agent must interpret from the name alone.

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%, so the description carries the burden. It fully documents 'view' (both enum values, default, recommended choice), but says nothing about institution_key_or_url — whether it accepts a slug, key, or URL. One of two parameters is well covered; the other is left to inference.

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 (Fetch) and resource (agent-oriented context for a Lacuna institution), and distinguishes itself from get_institution_authors by naming that sibling's role for paging. The phrase 'agent-oriented context' is slightly abstract, but the view parameter explanation resolves most ambiguity.

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

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

Gives explicit guidance for choosing between the two view modes, flags 'context' as the recommended default, and routes the agent to get_institution_authors for complete author pagination. It lacks guidance on when not to use this tool (e.g., vs get_author_context or search_lacuna), so it stops short of a full 5.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world, so the safety profile is covered. The description goes well beyond them: it explains the include_resources default and that non-context views ignore it, that figure_limit only affects context view and that 0 suppresses previews while keeping a truncation signal, and that versions are surfaced for follow-up fetches.

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 core action, then uses tight bullets per view where each line earns its place. It is somewhat long, but the length is justified by seven enum values and three documented parameters; a few clauses (e.g., repeated mention of context-view-only options) could be trimmed.

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

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

Covers the four parameters, the default view, resource inclusion, and figure limiting, and even outlines the response shape of each view despite an output schema existing. Nothing an agent needs to invoke this correctly is missing.

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

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

With 0% schema coverage, the description carries the full burden and does so thoroughly: all seven `view` enum values are defined with what each returns, `include_resources` default and view-specific behavior are stated, and `figure_limit`'s default, scope, and 0-value semantics are explained. This is exactly the compensation a 0%-coverage schema requires.

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 ("Fetch") and resource ("a Lacuna paper") plus the two accepted identifier forms (artifact id or paper URL). It is immediately distinguishable from siblings like get_hypothesis, get_direction, and get_resource, which fetch different resource types.

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 per view: "context (default, recommended)... Start here for almost everything," "preview... Use for citation-style display," and "full... Cheaper than context when you only need basic metadata." It also routes the agent to the sibling get_resource for deeper resource details.

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, openWorld, non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: it discloses the shape of the payload (facets, provider metrics, README/card excerpt, publications with relationship types) and the cross-tool handoff to get_paper.

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 and input contract, then the return contents. The mid-section becomes a long comma-separated enumeration of response fields, some of which the output schema already carries, so a few tokens are not fully earning their place.

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

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

For a single-parameter read tool with an output schema, the essentials are covered: what the resource types are, the accepted identifier formats, what comes back, and how to chain into get_paper. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden for the single parameter — and it does, specifying both an art_... artifact ID and a URL form embedding that ID. It could be stronger by noting failure behavior for malformed IDs or non-Lacuna URLs.

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 (fetch) and resource (Lacuna research resource), then immediately disambiguates what a 'resource' is by enumerating its four types (repository, dataset, model, demo). No sibling tool targets the same object, so the agent can route here 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?

Explains the two acceptable input forms (art_... ID or a /resource/<slug>/art_... URL) and gives a concrete follow-on path: pass a returned publications paper_id to get_paper. It lacks an explicit 'when not to use this' or a pointer back to search_lacuna for discovering IDs, which keeps it 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds real behavioral detail: the 'context' view drops the duplicated venue block and full year histogram server-side, caps top authors, and always includes the requested year. It stops short of noting result-size limits or pagination, but the response-shaping behavior is well disclosed.

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

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

Front-loaded with the core action, then a key-format warning, then a structured bullet list for the view enum. No filler sentences; each block maps to a decision the caller must make.

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

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

With an output schema present, return values need not be described, and the description covers everything else needed to call correctly: input format, key discovery path, view trade-off, and year semantics. Nothing material is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: it explains the opaque-hash format and URL alternative for venue_key_or_url, defines both enum values of view with concrete content differences, and clarifies that year is always included in the recent-activity slice.

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 ('Fetch agent-oriented context for a Lacuna venue') plus the optional scoping dimension (year). It is immediately distinguishable from siblings like get_author_context, get_institution_context, and search_lacuna.

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

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

Explicitly tells the agent how to obtain the required input ('find the key first via search_lacuna(search_type="venue") or pass a /venue/... page URL') and gives a clear when-to-use rule for each view, marking 'context' as default and recommended over 'full'.

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 bar is lower, yet the description adds substantial operational context: resource search constraints (no date_from/date_to, venue, year sorting, or semantic ranking), that resource_kind/provider filters require search_type 'resource' or 'all', that author_id_or_url requires 'paper', and that semantic ranking cannot use year sorting. These combination rules are the main reason this scores well; it stops short of describing pagination or result-count behavior for the general case.

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

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

The description is long, but the tool has 13 parameters with zero schema documentation, so most sentences are load-bearing and each paragraph maps to a coherent theme (purpose, routing, resources, ranking, filters). It is front-loaded with purpose and alternatives; density is high but waste is low.

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

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

An output schema exists, so return values need not be explained, and the description instead covers what the schema cannot: filter compatibility rules, ranking-mode restrictions, and the get_paper/get_resource follow-up path including linked_paper_count and context_url. Combined with the annotations covering safety semantics, an agent has enough 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 description coverage is 0% across 13 params, so the description carries the full burden and largely meets it: search_type values, resource_kind values, provider values, ranking_profile options, sort options, date bound formats (YYYY / YYYY-MM / YYYY-MM-DD, inclusive), author_id_or_url input format, and fields names/weight syntax (0 < weight <= 100) are all spelled out. limit, offset, and the purpose of venue outside the resource caveat are left undocumented, so it is not fully compensating.

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 and resource: 'Search Lacuna's ML/AI corpus for papers, research directions, authors, venues, institutions, novel research hypotheses, and research resources.' It enumerates exactly what entity types are covered, letting an agent separate this broad search tool from the narrow get_paper/get_resource/get_hypothesis siblings 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?

Explicit routing is provided: 'For novel ML/AI research ideas, use search_type="hypothesis", then get_hypothesis on promising results', and 'Use paper for literature and get_paper to read a result' with a stated exclusion ('Use other sources for biographies, news, and non-research web content'). It also names follow-on tools (get_resource, get_paper) and the conditions that select them.

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