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?

Beyond the readOnly/idempotent annotations, the description details the two response shapes: 'context' contains summary_markdown and truncation markers, while 'full' is the raw cluster record and cheaper. This adds meaningful behavioral context about what the agent will receive.

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 the core purpose, then structured with a clear explanation of the view parameter and its two distinct options. Every sentence adds value with no 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?

Given the presence of an output schema and simple parameter set, the description covers the essential purpose, the only configurable parameter's behavior, and the trade-offs between views. It is sufficient for an agent to select and invoke this tool 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 description thoroughly explains the 'view' parameter, including the exact semantics and trade-offs of 'context' vs 'full'. The 'cluster_id_or_url' parameter is self-evident from its name and required status, so the description compensates well despite 0% schema coverage.

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 'Fetch a Lacuna research direction/cluster,' using a specific verb and resource. It differentiates from siblings by focusing on fetching a single direction vs search or related-entity tools, and further defines the view options that shape the response.

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 when you have a cluster_id_or_url and provides guidance on choosing view ('context' recommended, 'full' for basic metadata). However, it does not explicitly state when to prefer this tool over alternatives like search_lacuna or get_direction_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, 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?

Annotations declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds behavioral context beyond these: it details the response shapes for each view, explains the `figures_truncated` signal, and describes the effect of passing 0 to figure_limit. No contradictions with annotations.

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

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

The description is structured with a clear lead sentence, a summary of view categories, and a bulleted list that makes each view self-explanatory. Every sentence adds value; no filler or redundancy. The length is justified by the complexity of the view options.

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 three parameters, one enum, and an output schema, the description covers all relevant aspects: how to identify the paper, which view to use for what purpose, and how the optional parameter behaves. The presence of an output schema does not reduce the need for the view explanations, and the description provides them completely.

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. It thoroughly explains `artifact_id_or_url` (paper identifier), enumerates and explains every `view` enum value, and defines `figure_limit` (caps figure preview, server default 3, 0 suppresses with signal). This goes far beyond the bare 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 opens with a specific verb+resource: 'Fetch a Lacuna paper by artifact id or paper URL.' It clearly distinguishes from sibling tools by specifying the Lacuna paper entity and the identifier format, and enumerates distinct response views that clarify scope.

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

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

It gives explicit usage guidance: 'Start here for almost everything' for context view, 'Cheaper than context when you only need basic metadata' for full view, and 'Use for citation-style display' for preview. This directly helps an agent select the appropriate view and implicitly when to use this tool (when an artifact ID/URL is available).

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?

The description discloses important behavioral details beyond annotations: ranking profiles (lexical vs semantic), restrictions on combining semantic ranking with year sorting, inclusive date format constraints, and field weighting syntax. It also explains that fields must exist on the selected search_type. No contradiction with annotations.

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

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

The description is structured in clear short paragraphs, each addressing a specific parameter group. It is dense but every sentence provides necessary operational detail, and the front-loaded main purpose ensures quick comprehension.

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 10 parameters and zero schema descriptions, the description covers all parameter semantics and usage constraints. The existence of an output schema means return format need not be in the description. This is a complete and self-sufficient description for correct tool 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?

With 0% schema coverage, the description fully compensates by explaining every parameter: search_type aliases, ranking_profile options, sort values, date formats, and fields syntax with examples. This is essential context that the schema lacks, making the description highly valuable for correct invocations.

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 searches Lacuna's ML/AI corpus for multiple entity types (papers, directions, authors, venues, institutions, hypotheses). It distinguishes itself from sibling tools like get_hypothesis and get_paper by focusing on search rather than retrieval of specific entities.

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 guidance is provided: use search_type='hypothesis' for novel research ideas and then call get_hypothesis. It also instructs to use other sources for biographies, news, and non-research content, clearly delimiting when this tool is appropriate versus alternatives.

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