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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: caveats about affiliation data being incomplete/outdated, no biography/employment history, latency implications of include_neighbors, and server-side collection caps (100). This significantly exceeds what annotations alone provide.

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

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

The description is well-structured: a lead sentence, a data-caveat paragraph, and a bulleted view explanation. Every section earns its place, though the affiliation caveat could be slightly more concise without losing meaning. It is appropriately sized for the complexity.

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

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

The description is complete for this tool's complexity: it explains response shape variants, data reliability limits, server caps, and neighbor latency. Since an output schema exists, it need not describe return fields in detail. No major gaps are evident.

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

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

The input schema has 0% description coverage, so the description must compensate. It thoroughly explains the 'view' parameter with distinct response shapes and the 'include_neighbors' parameter with latency trade-offs. The 'author_id_or_url' parameter is self-explanatory but lacks format details, which is 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?

The description clearly states the tool 'Fetch agent-oriented context for a Lacuna author' with a specific verb and resource. It distinguishes from sibling tools by describing a composite context (papers, directions, impact) rather than a single aspect like papers or directions.

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

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

The description provides clear context for when to use this tool, especially through the view parameter choices ('context' recommended vs 'full') and the include_neighbors option. However, it does not explicitly name alternative sibling tools for specific needs, though the context implies this is the go-to for a holistic author profile.

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

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

Annotations already communicate read-only, idempotent, non-destructive behavior. The description adds the useful behavioral detail that only one page is returned at a time, and that directions are 'named', which is not captured by annotations. No contradictions.

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

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

The description is a single, concise sentence with the verb first and no unnecessary words. It earns its place entirely, achieving high clarity in minimal space.

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

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

For a simple paginated read-only tool with a full output schema and robust annotations, the description covers the core purpose and pagination. Missing details include parameter clarification and explicit sibling differentiation, but the basic usage is clear enough for straightforward selection and invocation.

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

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

The schema has 0% description coverage, so the description must compensate. It only hints at limit/offset via 'one page', adding some meaning, but does not explain author_id_or_url or the exact semantics of limit/offset beyond naming. This is minimal compensation for the lack of 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 clearly states the tool fetches one page of an author's named research directions, using a specific verb and resource. It distinguishes itself from siblings like get_direction (a single direction) and get_author_papers (papers) by focusing on the author's directions with pagination.

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 pagination hint 'one page' implies a use case for paging through results, but the description gives no explicit when-to-use vs alternatives, no exclusions, and does not mention sibling tools. Usage context is implied rather than directly 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 read-only, idempotent, and non-destructive behavior. The description adds 'one ranked page' to indicate pagination and 'neighboring/similar' to clarify the concept, but it does not disclose additional behavioral traits such as ranking criteria or error handling.

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

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

The description is a single, well-structured sentence with the action verb first and no unnecessary words. It is concise, front-loaded, and easy to parse.

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

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

Although the tool has an output schema and safety annotations, the description lacks details on what qualifies as a 'neighbor' or how ranking works. It also does not explain the required input parameter, leaving some contextual gaps for an agent to 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 description coverage is 0%, and the description does not explain any of the three parameters (author_id_or_url, limit, offset). While parameter names are somewhat self-explanatory, the description fails to compensate for the lack of schema descriptions, adding no extra meaning beyond the schema.

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

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

The description clearly states the action ('Fetch') and the resource ('neighboring/similar Lacuna authors'), distinguishing it from sibling tools like get_author_papers or get_author_context. The phrase 'one ranked page' also signals pagination, making the purpose specific and clear.

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

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

The description implies usage for retrieving similar authors but does not explicitly state when to use it or contrast with alternatives. No exclusions or alternative tool mentions are provided, so guidance is limited to the implied context.

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

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

Annotations already establish read-only, non-destructive, and idempotent behavior. The description adds valuable behavioral context by specifying that results are paginated ('one page') and ordered newest-to-oldest, which is not captured in annotations.

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

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

The description is a single, front-loaded sentence with no unnecessary words. It efficiently conveys the action, resource, pagination scope, and ordering.

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

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

The description covers the core purpose and one behavioral detail, but it lacks explicit usage guidelines and parameter explanations. The presence of an output schema and clear annotations partially offsets these gaps, making it minimally viable but not fully comprehensive for a tool with 3 parameters and several siblings.

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 description coverage, the description needed to compensate by explaining the parameters. It only implies pagination ('one page') without naming limit/offset or explaining their semantics, and it does not clarify the format or valid values for author_id_or_url beyond its name.

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

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

The description uses the specific verb 'Fetch' and clearly identifies the resource as 'an author's papers', with pagination ('one page') and ordering ('newest to oldest'). This distinguishes it from sibling tools like get_paper (single paper) and get_direction_papers (papers for a direction).

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

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

The description implies that the tool is for retrieving an author's papers, but it does not explicitly state when to use it over alternatives such as get_author_directions or get_direction_papers. There is no when-not-to-use guidance or mention of alternative 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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description earns credit by disclosing view behavior: context returns a capped agent-oriented summary with truncation markers, while full returns the raw upstream record and is cheaper for metadata-only 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?

Purpose is front-loaded in the first line, followed by input format and then a well-structured bulleted breakdown of the two views. Slightly verbose with line breaks, but every sentence carries 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 fully described, yet the description still usefully characterizes what each view returns. Input format and view semantics are covered; only sibling routing is absent.

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

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

Schema coverage is 0%, so the description must carry the load, and it does. It explains cluster_id_or_url accepts either a numeric ID or a URL ending in that number, and it precisely defines both enum values of view, including the default and the trade-off between 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: 'Fetch a Lacuna research direction/cluster.' The 'direction/cluster' wording disambiguates the terminology, but it doesn't explicitly differentiate itself from siblings like get_direction_papers or get_author_directions, so an agent still infers the boundary.

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 view parameter (context default/recommended vs full when only metadata is needed), but says nothing about when to choose get_direction over sibling tools, nor any 'when-not' conditions. Input-format guidance ('numeric cluster ID or URL') is not tool-selection 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, and the description adds valuable behavioral detail: payload shapes, size implications, and what the compact view discards (raw blob, cluster internals). This goes beyond 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?

The description is concise, front-loaded with a clear opening sentence, and uses bulleted view details. No redundant text.

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

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

For a read-only paginated fetch with an output schema, the description covers the two views and their tradeoffs, and mentions pagination. Minor gaps: no explicit discussion of default page/limit behavior, but those are in the schema.

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

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

With 0% schema description coverage, the description explains the view parameter in depth but leaves cluster_id_or_url, page, and limit to their schema names. The required parameter's semantics are implied by the tool name but not elaborated.

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

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

The description clearly states the tool fetches paginated papers for a Lacuna research direction/cluster, using a specific verb and resource. It distinguishes from siblings like get_paper (single paper) and get_author_papers (author-specific papers).

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

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

Provides clear context for the view parameter, recommending compact by default and reserving full for raw metadata needs. It does not explicitly name alternative tools, but the purpose is unambiguous enough for an agent to infer when 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?

The description adds behavioral detail beyond the annotations by explaining what each view returns, including that the 'context' view drops the raw upstream record server-side and that 'full' includes version history and signal counts. It discloses side effects (dropping duplicate markdown) and the content shape, with no contradiction to the readOnlyHint.

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

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

The description is compact and well-structured: a one-sentence purpose, a usage note, and a bulleted list of views. Every sentence adds value, and the front-loaded structure makes it easy to scan.

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

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

Given the tool has only two parameters and an output schema, the description covers the essential decision points: what each view returns, which is default/recommended, and the scenario for 'full'. It is complete for an agent to select and invoke the tool correctly, and the output schema covers return values.

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 'view' parameter is thoroughly explained with its two enum values, default, and recommendation. The 'hypothesis_id_or_url' parameter is not explicitly described beyond its name and the note that it is used after search_lacuna, which is somewhat implicit given the 0% schema description coverage. However, the name is self-explanatory and the usage guidance fills in the context, so it is only slightly below full compensation.

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 clear, specific verb+resource statement: 'Fetch a generated novel ML/AI research proposal from Lacuna.' It distinguishes the tool from siblings by focusing on proposals and explicitly ties it to search_lacuna, making its purpose 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?

It provides explicit when-to-use guidance: 'Use after search_lacuna(search_type="hypothesis") to inspect a proposal.' It also explains when to choose each view, recommending 'context' by default and reserving 'full' for cases needing versions or signals, which is strong usage 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: it discloses that results are one page at a time, ordered by paper count, and how pagination works via output fields. This is sufficient transparency for a read-only tool.

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

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

The description is three short sentences, front-loaded with the core purpose. Every sentence earns its place: purpose, ordering, and pagination instructions. 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?

Given the tool's simplicity (3 params, no nested objects, output schema present), the description covers the essential points: what it fetches, ordering, and pagination. It could add a note on what institution_key_or_url refers to, but the parameter name and sibling tools provide enough context.

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

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

Schema description coverage is 0%, so the description must compensate. It does provide pagination-related context but does not explicitly explain the limit/offset parameters or the form of institution_key_or_url. The parameter names are fairly self-explanatory, and the output-pagination fields indirectly imply usage, but the description could be more explicit.

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

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

The description uses a specific verb ('Fetch') and resource ('one page of authors affiliated with a Lacuna institution'), clearly distinguishing it from sibling tools like get_institution_context or get_author_papers. The scope ('one page') and ordering ('by paper count') are also stated.

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

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

The description gives clear in-tool guidance: it tells the user how to page through results using authors_total, authors_returned, authors_offset, and authors_truncated. It does not explicitly mention alternatives/exclusions, but given no sibling tool serves the same purpose, the context is clear enough.

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

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

Annotations already indicate readOnly/openWorld/idempotent, and the description adds meaningful behavioral context: the 'context' view returns a 'capped top authors' list with 'the duplicated institution block dropped server-side,' while 'full' includes 'a bounded author list with explicit truncation metadata.' This goes beyond just stating the operation and clarifies response shape differences.

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 purpose in the first sentence. Bullet points efficiently explain the two views, and the final sentence directs to a sibling tool. No filler or redundant information.

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

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

Given the output schema exists and annotations cover safety, the description is largely complete: it explains the two response shapes, provides an alternative for full author listing, and gives a default recommendation. The only gap is the lack of detail on the institution identifier parameter, but overall the tool is well-specified for an agent to select and invoke correctly.

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

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

The input schema has 0% description coverage, so the description must compensate. The 'view' parameter is thoroughly explained with enum meanings and recommendations, but the required 'institution_key_or_url' parameter lacks any detail (e.g., format or example) beyond its self-descriptive name. The description mentions 'a Lacuna institution' but does not explicitly define what a key or URL looks like.

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: 'Fetch agent-oriented context for a Lacuna institution,' clearly distinguishing it from sibling tools like get_author_context and get_venue_context. It further differentiates this tool from get_institution_authors by noting that the latter is for paging through the complete author 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?

The description explicitly recommends the default 'context' view and explains when to use it vs. the 'full' view. It also provides an explicit alternative: 'Use get_institution_authors to page through the complete author list,' which tells the agent when NOT to use 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?

Beyond the readOnly/idempotent annotations, it discloses non-obvious behavior: include_resources defaults to True for context and full views, other views ignore it, figure_limit defaults to 3 server-side, and passing 0 suppresses previews while retaining a `figures_truncated` signal. It also explains that other versions require reading the returned version list's artifact ID.

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 one-line purpose, then a bulleted view breakdown that is scannable. It is somewhat long, and 'other views ignore this option' plus the include_resources explanation repeat the same default, but nearly every sentence carries usable routing detail.

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 need not explain return shapes, and it correctly focuses on view selection, defaults, and cross-tool handoff. For a 7-mode fetch tool, an agent has everything needed to pick a view and 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 description coverage is 0%, so the description must carry all meaning, and it does: every enum value of `view` gets a definition and intended use, and both `include_resources` and `figure_limit` are explained with defaults and edge-case behavior. Only artifact_id_or_url is left to its name, which 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 a Lacuna paper') plus the accepted identifier forms (artifact id or paper URL). It also names 'get_resource' as the follow-up tool, so an agent can locate it against siblings like get_hypothesis or get_author_papers 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 explicit routing: "context" is the default and recommended starting point "for almost everything," with per-view guidance on when to prefer full (cheaper, basic metadata), preview (citation display), and the single-field views. It also states the condition for switching views ('Pass a resource entry's id to get_resource').

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 burden is light; the description adds real behavioral context by enumerating the response payload (facets, provider metrics, README excerpt, linked publications with relationship types, related directions). It does not cover failure modes for malformed IDs or slugs.

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 one-line purpose, then input format, then response shape. Every sentence carries information, though the response-field enumeration is long and partially duplicated by the output 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?

An output schema exists, so describing return values is redundant-but-helpful rather than necessary. Input format and sibling routing are covered; missing only error/auth behavior, which is minor for a read-only lookup.

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 single parameter — and it does, specifying that it accepts an 'art_...' artifact ID or a Lacuna resource URL of the form /resource/<slug>/art_..., which is the key detail an agent needs to construct a valid call.

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: code repository, dataset, model, or demo), which concretely bounds the tool and separates it from generic siblings like search_lacuna or get_paper.

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 input form and routes the agent onward — 'Pass a publication's paper_id to get_paper' — which is genuine usage guidance. It does not, however, state when to choose this tool over search_lacuna or when-not conditions, so it stops short of full when/alternatives 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?

Beyond the annotations (readOnly, idempotent, non-destructive), it discloses that venue keys are opaque hashes, that the context view drops duplicated venue blocks and full histogram, and that the requested year is always included. This adds meaningful behavioral detail.

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 well-structured and every sentence provides useful information, with the key format and view modes clearly explained. 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?

The description covers key sourcing, view differences, and year inclusion. The output schema presumably documents return fields, so it's not necessary to explain them. Minor ambiguity in 'agent-oriented context' and lack of explicit year range, but overall 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?

With 0% schema coverage, the description compensates well: it explains venue_key_or_url format and how to find it, and details view options. Year gets partial treatment as 'optionally scoped to a year' but lacks explicit type/range, though schema provides the type.

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 it fetches agent-oriented context for a Lacuna venue, with a specific verb and resource. It distinguishes itself from sibling tools by focusing on venue context, and provides guidance on venue keys.

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 how to obtain the venue key via search_lacuna and recommends the 'context' view, but lacks explicit when-not-to-use or alternative tool pointers beyond that.

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, open-world, non-destructive, but the description adds substantial behavioral constraints beyond them: resource search does not support date_from/date_to, venue, year sorting, or semantic ranking; semantic ranking cannot use year sorting; fields cannot be combined with semantic ranking and weights must fall in 0 < w <= 100. These are exactly the limitations an agent needs to avoid erroring.

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 workflow routing, then parameter behavior; each block earns its place given 13 parameters with zero schema documentation. It is dense and occasionally repetitive (resource filters are restated across several sentences), so it stops just short of maximally tight.

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

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

An output schema exists, so return values need no explanation, and annotations cover the safety profile; the description fills the remaining gaps (filter interdependencies, ranking restrictions, date formats, follow-up tools). 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 description coverage is 0%, so the description carries the full burden and largely does: it documents search_type values, resource_kind and provider enums and their dependency on search_type, ranking_profile options and their applicability, sort values, inclusive date bound formats, author_id_or_url semantics and its search_type=paper requirement, and fields syntax with weight bounds. Only limit, offset, query, and venue receive no explanation, which is a minor residual 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 (search) and resource (Lacuna's ML/AI corpus), and enumerates the entity types retrievable: papers, directions, authors, venues, institutions, hypotheses, and resources. It clearly separates itself from read-style siblings like get_paper and get_resource, which it names as follow-up steps.

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 guidance: use search_type=hypothesis for novel ideas then get_hypothesis; use paper for literature then get_paper; use resource with resource_kind=dataset for benchmarks. It also names the conditions under which filters apply (resource_kind/provider require search_type resource or all) and the alternatives for biographies/news.

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