Lacuna Research MCP

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

With annotations already covering readOnly/idempotent/non-destructive, the description still adds substantial behavioral and data caveats: server-side capping at 100, the dropped duplicate nested author record, significant latency from neighbor computation, and an explicit warning that the `affiliation` field may be stale and must not be used to infer biography or employment.

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 and then the view semantics; every sentence adds usable information. It is somewhat long and mildly repetitive ('Lacuna's compact author context'), but nothing is pure 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?

An output schema exists, yet the description still usefully characterizes both response shapes, which is more than required. The only missing piece an agent needs to invoke correctly is the accepted form of the required author_id_or_url.

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 carry all parameter meaning. It explains the two `view` shapes in concrete terms (what fields differ, what is capped/dropped) and the effect and cost of include_neighbors. It never explains the format or acceptable values of the required `author_id_or_url`, which is the one remaining 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 ('Fetch agent-oriented context for a Lacuna author') and enumerates what the returned context contains (papers, impact_directions). It does not explicitly name or differentiate itself from the sibling tools get_author_neighbors/get_author_papers, though the include_neighbors note implies the overlap.

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 for the `view` parameter by labeling 'context' as default and recommended versus 'full', and flags the latency cost of include_neighbors. It stops short of naming alternatives (e.g., when to prefer get_author_neighbors over include_neighbors=True), so it is context without exclusions.

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

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

Annotations already declare readOnlyHint=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 declare read-only, idempotent, non-destructive, open-world behavior, so the bar is lower. The description adds real value beyond them: how the response shape is capped (papers/authors/related_directions), the presence of truncation markers, and the relative cost of each view.

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 imperative followed by a bulleted enum breakdown; each sentence earns its place. Slightly verbose in the view bullets, but the structure makes the tradeoff scannable.

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

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

An output schema exists, so return values need no prose; the description still clarifies what each view actually returns. With only one required parameter and full enum/identifier guidance, 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 0%, so the description must carry the load, and it does: it explains that cluster_id_or_url accepts a numeric ID (with an example) or a URL ending in that number, and fully characterizes the 'view' enum including default and output 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?

States a specific verb and resource ('Fetch a Lacuna research direction/cluster') and clarifies the domain term with its identifier form. It does not explicitly distinguish itself from close siblings like get_direction_papers or get_author_directions, so it falls just short of a 5.

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

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

Gives clear guidance on the tool's own options: which view to pick, that 'context' is the default and recommended, and the cost tradeoff for 'full'. It offers no guidance on when to use this tool rather than a sibling (e.g. get_direction_papers vs this), so it stops short of explicit alternatives.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds real value beyond that by disclosing pagination and exactly what the compact view strips away (raw upstream info blob, levels.cluster internals) versus what full retains.

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 tool's core action in one sentence, then uses a tight bullet list keyed to the view values. No filler; every clause either names a view option or explains what it changes in the payload.

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-value documentation is not required, and the description still usefully characterizes the two response shapes. The remaining gap is pagination mechanics (meaning of page/limit defaults), but for a read-only list tool this is close to complete.

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

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

Schema description coverage is 0%, but the description thoroughly explains the 'view' enum (both values, default, tradeoffs), which is the highest-risk parameter. However, page, limit, and especially the string-or-integer cluster_id_or_url (which accepts a URL or id) are left entirely undocumented, so it only partially compensates for the missing 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?

States a specific verb (fetch) and resource (paginated papers associated with a Lacuna research direction/cluster) with clear scope. It is easily distinguishable from siblings like get_direction (the cluster itself), get_paper (single paper), and get_author_papers (papers by author).

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 guides the view choice: 'compact' is the default and recommended for citation-ready rows, 'full' only when raw upstream metadata is needed. This is strong when-to-use guidance for the main decision, though it never contrasts this tool against alternatives like search_lacuna or get_direction.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description goes further by disclosing a server-side behavior—the raw upstream record is dropped in the 'context' view because its markdown duplicates summary_markdown—and where proposal bodies live in 'full' (versions[].markdown). This is substantive 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?

Front-loaded purpose followed by a clean bulleted breakdown of view modes; every sentence carries information. The parenthetical about duplicated markdown is slightly dense but justified since it explains the field dropping.

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 re-explained, yet the description still clarifies response shapes and where bodies live. For a two-parameter read tool with full annotation coverage, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description must carry the load; it fully explains both enum values of 'view' with the default and a recommendation. It does not explain the accepted format of hypothesis_id_or_url beyond its name, leaving a small 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 ('Fetch a generated novel ML/AI research proposal') and names the source (Lacuna), which separates it from sibling retrievers like get_paper or get_direction. An agent can tell what it 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?

Explicitly names the prerequisite call (search_lacuna with search_type="hypothesis") and gives a when/when-not rule for the view parameter: 'full' only when versions or signals are needed, otherwise context is 'default, recommended'.

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 and idempotency profile is covered. The description adds that results are ordered by paper count, which is genuinely useful behavioral context not in the annotations. It does not mention auth requirements or rate limits.

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 no waste, and the core purpose is front-loaded. The second sentence is appropriately terse pagination guidance.

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 an output schema, the return-value explanation is not needed. However, with 0% schema coverage on three input parameters and no sibling differentiation, the definition leaves gaps an agent must fill from the schema 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 must compensate for three undocumented parameters. It names none of them (limit, offset, institution_key_or_url) and provides no format for institution_key_or_url (key vs. URL). The pagination response fields are mentioned, but the input parameters remain unexplained.

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 (authors affiliated with a Lacuna institution) with clear pagination scope. It does not differentiate from siblings like get_author_neighbors or get_institution_context, but the institution-author combination is specific 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?

Provides pagination guidance via the response fields, which implies usage for complete list enumeration. However, it does not say when to use this versus get_institution_context or get_author_papers, and no exclusions 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 cover the safety profile (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false), so the bar is lower, yet the description still adds real behavioral detail: server-side removal of the duplicated institution block, author capping in the compact view, and explicit truncation metadata in the full view. It does not mention auth needs or rate limits, but the shape differences are genuinely useful context beyond the annotations.

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

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

Front-loaded with the purpose, then a scannable two-bullet breakdown keyed to the view enum, then the routing sentence. Slight redundancy between "duplicated institution block dropped server-side" and "duplicated institution record," but no filler sentences.

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 spelled out, and the description still usefully characterizes the two response shapes and their truncation behavior. The only meaningful gap is the format of institution_key_or_url, which is required for every call and never 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?

Schema description coverage is 0%, so the description must carry the load. It does this well for view, explaining the semantic difference between the two enum values (compact vs. complete, and which is recommended), but institution_key_or_url is never addressed — it is not stated whether a raw key, a full URL, or both forms are accepted, leaving half the parameters undocumented.

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

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

States a specific verb and resource ("Fetch agent-oriented context for a Lacuna institution") and immediately distinguishes itself from the closest sibling by naming get_institution_authors for complete author lists. An agent can separate this from get_institution_authors or get_venue_context 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 clear routing guidance: the default "context" view is explicitly labeled recommended/compact, and author pagination is explicitly delegated to get_institution_authors. It lacks an explicit when-not-to-use case (e.g., when the agent only needs a venue or author), 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 declare readOnlyHint/idempotentHint/openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond that: default view, per-view return shapes, that non-context views ignore include_resources, and that figure_limit=0 still emits a figures_truncated signal. It stops short of pagination or error 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?

Front-loaded with purpose, then structured bullets per enum value; the length is justified by seven view options that each need disambiguation. Sentences are dense with information rather than filler.

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

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

Even though an output schema exists and annotations cover safety, the description explains what each response shape contains and the defaults/truncation signals an agent needs. Nothing required to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning, and it does so well for view (each of the 7 enum values explained), include_resources (default true, effect per view, False behavior), and figure_limit (default 3, 0 semantics). The required artifact_id_or_url is only lightly characterized, with no format guidance for id vs URL.

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

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

The opening line states a specific verb and resource ('Fetch a Lacuna paper by artifact id or paper URL') and the rest of the description makes the tool's scope unmistakable versus siblings like get_resource and search_lacuna. An agent can distinguish it 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 concrete selection guidance within the tool ('context': 'Start here for almost everything'; 'full': 'Cheaper than context when you only need basic metadata') and routes the agent to get_resource for resource detail. It does not, however, say when to prefer get_paper over siblings such as search_lacuna 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds real behavioral context beyond that: the tolerated input formats (bare ID vs. full URL) and the richness of the payload (facets, provider metrics, README/card excerpt, publications with relationship types). It does not discuss auth, rate limits, or error behavior, but for a read tool that is a minor 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?

Front-loads the verb and resource, then input formats, then payload contents. The long enumeration of return fields is somewhat verbose and overlaps with the output schema, but the sentences remain information-bearing and there is no filler.

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

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

With an output schema present, the response enumeration is redundant but harmless; the essential pieces — what the tool fetches, what identifier it takes, and the handoff to get_paper — are all present. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 0%, so the description must carry the parameter's meaning, and it does: the single parameter accepts either an art_... artifact ID or a resource URL containing that ID, including the exact URL shape. This adds genuine disambiguation beyond the bare 'string' schema entry.

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 a Lacuna research resource') and enumerates the concrete artifact types (code repository, dataset, model, demo). It also names the sibling it routes to ('Pass a publication's paper_id to get_paper'), so an agent can distinguish it from get_paper 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?

Clearly describes accepted input forms (an art_... artifact ID or a /resource/<slug>/art_... URL) and points to get_paper for reading linked publications, which gives usable when-to-use context. It stops short of explicit when-not guidance or alternative lookup paths for other resource types.

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

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

Annotations already cover read-only/idempotent/non-destructive/open-world, and the description adds real behavioral detail beyond them: the "context" view drops the duplicated venue block and full year histogram server-side, caps top authors, and filters placeholder clusters. It stops short of describing auth, rate limits, or when "full" is actually needed, keeping it at a 4.

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 in the first sentence, key format and view semantics follow in clearly separated blocks, and the bulleted view comparison is scannable. The prose is slightly longer than strictly needed, but every sentence carries usable information.

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

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

With an output schema present the description needn't enumerate return fields, and it appropriately focuses on how the two views differ in shape and what gets trimmed. Combined with annotations that carry the safety profile, an agent has everything needed to call this correctly, though the year parameter's exact semantics remain slightly underdetermined.

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 parameter burden and largely does: venue_key_or_url is explained as an opaque hash with two ways to obtain it, and view's two enum values are contrasted with their trade-offs. Year is documented only loosely ("optionally scoped to a year", "the requested `year` is always included"), which is the one thin spot.

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") and immediately bounds the scope with "optionally scoped to a year". It also distinguishes itself from search_lacuna by casting that tool as the key-lookup step rather than a substitute. An agent can tell what this does without opening the schema.

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

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

Gives concrete entry guidance: find the key via search_lacuna(search_type="venue") or pass a /venue/... URL, and recommends "context" over "full" by default. It does not say when to prefer this over adjacent siblings like get_institution_context or get_resource, so the routing is clear but not exhaustive.

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

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

Annotations already cover safety (readOnly, idempotent, openWorld, non-destructive), and the description layers on real behavioral constraints: resource search ignores date_from/date_to, venue, year sorting and semantic ranking; semantic ranking cannot use year sorting; filters must pair with search_type resource/all and then only resources are returned. These are non-obvious caveats an agent could not infer.

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?

Well front-loaded (purpose, then follow-up routing, then per-parameter reference) and organized into digestible blocks. It is dense and reference-manual length for a 13-parameter tool, with mild redundancy (the resource filter restriction is restated after the resource support list), but nearly every sentence is load-bearing.

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, and the description still adds useful result-shape context (external url, context_url, linked_paper_count). Across 13 parameters with zero schema descriptions, the description leaves no mode, filter interaction, or format ambiguity that would cause a misinvocation.

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 there are no enums, so the description carries the full burden — and it does: it enumerates search_type, ranking_profile, sort, resource_kind, provider values, date bound formats (YYYY / YYYY-MM / YYYY-MM-DD, inclusive), the fields weighting syntax with its 0 < weight <= 100 rule, and the author_id_or_url constraint. Only limit/offset are left undocumented, which are conventional.

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') and enumerates exactly what is retrievable (papers, directions, authors, venues, institutions, hypotheses, resources). It distinguishes itself from siblings by routing follow-up work to get_hypothesis, get_paper, and get_resource by name.

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 branches: search_type="hypothesis" plus get_hypothesis for novel ideas, "paper" plus get_paper for literature, resource_kind="dataset" for benchmarks, and 'other sources' for biographies/news. It also states conditions that select each mode (e.g. filters require search_type resource or all).

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