OpenArx

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

No annotations are provided, so the description carries the full burden. It mentions that the output is 'built on LLM-extracted entities + chunk classifications', giving insight into the method. However, it does not disclose any side effects, limitations, or performance characteristics (e.g., processing time, costs). The description is adequate but not thorough.

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 two sentences: the first states the action and output, the second provides usage context. No superfluous information; every sentence earns its place.

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

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

The tool has 4 parameters (1 required) and no output schema. The description explains the output structure reasonably. It could mention prerequisites (e.g., documents must exist) or error scenarios, but overall it covers the key aspects for an AI agent to decide to use it.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add extra meaning to the parameters beyond what the schema provides. The output description is in the tool description, not parameter-specific. Hence, minimal additional value.

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

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

The description uses specific verbs ('Generate side-by-side comparison'), identifies the resource ('2-5 papers'), and describes the output ('structured grid: shared entities...'). It clearly distinguishes from sibling tools, many of which are search or retrieval tools, and there is no other comparison tool in the sibling 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 says 'Use for systematic literature review, surveying competing approaches, identifying research gaps' indicating appropriate contexts. While it does not provide explicit alternatives or when-not-to-use, the context is clear and the use cases are well-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?

With no annotations, the description carries full burden, and it excels: it discloses that drafts are not indexed, do not appear in get_my_documents, that dry_run does not consume content_ref, that the response echoes a would_save block, and that agents cannot edit draft content. These are non-obvious behavioral traits beyond the schema.

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

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

The description is long but well-structured, with front-loaded purpose, then workflow, then caveats. Minor redundancy (edit_url mentioned twice) and a dense block of caveats warrant a 4 rather than 5, but every sentence adds useful information for a complex tool.

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

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

Given the complexity (7 params, nested objects, no output schema), the description covers prerequisites, return values, side effects, limitations, and edge cases (dry_run, unrecognized metadata, version binding). It is fully complete for an agent to invoke the tool correctly and interpret results.

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

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

Although schema coverage is 100%, the description adds substantial meaning: content_ref is required because drafts are file-only, metadata keys are dropped unless recognized and echoed, previous_document_id binds to a version chain, and dry_run validates without side effects. It clarifies run_id usage and ownership requirements, going well beyond 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 opens with a specific verb and resource: 'Create an editable draft in the OpenArx Portal instead of publishing immediately.' It clearly distinguishes from siblings like publish_draft and submit_document by emphasizing the draft workflow and returning draft_id/edit_url.

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 workflow guidance is given: 'first call create_upload_url, PUT your ZIP/PDF, then pass the returned file_id as content_ref.' It also states when not to use (drafts are file-only, no content editing) and points to publish_draft for metadata correction. This fully supports tool selection and invocation.

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?

With no annotations, the description fully discloses behavioral traits: the new version does not replace the old, previous chunks become 'not-latest', dry run shows validation without committing, and effects of omitted parameters (inherit from previous version). Limits and format requirements are also detailed.

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 fairly long but front-loaded with the most critical information. Every sentence adds necessary detail, though some reorganization could make it even more scannable. 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 tool has 28 parameters, no output schema, and no annotations, the description is remarkably complete. It covers all key aspects: behavior, constraints, content handling, inheritance, dry run, and limits. The agent can confidently use this tool based on the description 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?

Despite 100% schema coverage, the description adds significant value beyond the schema: explains mutual exclusivity of content parameters, inheritance for categories/keywords/language, dry run specifics, file format expectations for ZIP contents, and preference for content_ref over base64 for large files.

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 'Submit a new version of an existing document' and distinguishes it from similar operations by noting that the earlier version is not replaced and keeps its own identifier. This differentiates it from sibling tools like submit_document (new document) or publish_draft.

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 explicit guidance on when to use this tool, including content upload alternatives (content_ref preferred above ~10 KB), dry run for validation, and inheritance behavior for omitted fields. It also clarifies mutual exclusivity of content_archive_base64 and content_ref, and that inline text is no longer accepted.

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?

Discloses URL expiration (10 min), size limit (50 MB), single file, magic-byte check, and run_id attribution rules. No annotations provided, so description fully covers behavioral traits.

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

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

Four concise sentences, front-loaded with purpose, no redundancy. Every sentence adds value.

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?

Complete for the tool's purpose: describes input, constraints, and follow-up actions. No output schema, but the description compensates by explaining next steps.

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 covers parameters fully (100% coverage). Description adds helpful usage guidance for run_id and expected_content_type, enhancing understanding beyond 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?

Clearly states it requests a presigned PUT URL for uploading publishing content, distinguishing from siblings like submit_document and create_new_version by specifying the post-upload workflow.

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 says when to use (content >~10 KB) and what to do after (upload to URL, then pass file_id to other tools). Provides clear 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?

No annotations provided, but description fully covers behavior: searches papers/chunks, not claim graph, returns clusters with representative chunks, includes diversification cap and temporal bias note.

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?

Description is detailed and well-structured, but somewhat long. However, every sentence adds meaningful information, so earns a 4.

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 9 parameters and no output schema, description sufficiently explains return type (clusters with chunks) and provides enough context for correct invocation.

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

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

Schema coverage is 78%, so baseline is 3. Description adds value by explaining run_id attribution, diversification cap context, and how to use date parameters for temporal slicing.

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?

Clearly states it maps conceptual landscape across paper corpus, returning clusters not ranked list. Distinguishes from sibling tool methodist_explore_topic for claims.

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 says use for 'what approaches exist' queries, recommends over search for breadth, and gives temporal bias guidance with date parameters.

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?

No annotations provided, so description carries full burden. It discloses that results are LLM-extracted, filtered to performance metrics, and that certain non-performance attributes like model-size are excluded. It also notes possible empty results for non-numerical papers. Does not mention authentication or rate limits, but these are not critical for this 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 informative and well-structured, front-loading the main purpose and then providing details. A few sentences could be tightened, but overall it earns its length.

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 9 parameters and no output schema, the description does an excellent job explaining what the tool returns, when it works, and required filtering conditions. It covers scope, limitations, and use cases comprehensively.

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 89%, so baseline is 3. The description adds context about the output format and filtering logic, which helps interpret parameters, but does not add substantial new meaning per parameter beyond the schema's own 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 it queries structured benchmark scores from research papers, specifies the return fields (task, dataset, metric, score, method, paper, year), and distinguishes itself from general paper search by focusing on performance metrics. This is specific and distinct from sibling tools like search_keyword.

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

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

Explicitly states it is 'Best for ML benchmark / leaderboard papers' and may return empty for theoretical/survey papers. Provides clear use cases: SOTA tracking, trajectory analysis, comparing methods. Also specifies the requirement that at least one of task/dataset/metric must be provided.

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?

No annotations provided, so the description carries full burden. It discloses important behaviors: auto-resolution of arXiv-style DOIs, that identifiers resolve to specific versions (not mutable state), and run_id attribution requirements. This goes well beyond the schema.

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

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

Three sentences, all meaningful and front-loaded. No wasted words. Each sentence adds essential 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?

No output schema exists, so the description should ideally indicate what the tool returns. It does not mention the response format or content, leaving a gap in completeness despite good behavioral detail.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining auto-resolution for arXiv DOIs and the run_id attribution purpose, which are not in the 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 it finds a paper by external identifiers, listing specific ID types (OpenArx, DOI, arXiv, etc.). This distinguishes it from sibling tools that perform search or retrieval by other means.

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 an exact identifier is available, but does not explicitly exclude using it for keyword search or recommend alternatives. The context from sibling tools helps, but more explicit guidance would be better.

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?

With no annotations, the description carries full burden. It discloses that by default only top items per paper are returned, and detail=full is needed for complete lists. The run_id parameter description adds context about attribution. However, it does not mention authentication, rate limits, or that it is a read-only operation.

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 two sentences: first covers purpose and filters, second clarifies default output behavior. It is front-loaded with key information and contains no unnecessary 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 11 parameters and no output schema, the description explains the default output (top items per paper) and the detail parameter, which is sufficient. It could elaborate on the structure of return values, but the behavior is clear for a search 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 high (91%), so baseline is 3. The description adds value by explaining the detail parameter's effect ('top items per paper') and providing a detailed, context-rich explanation for run_id beyond the schema description. Other parameters are already well-described in 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 tool finds papers with associated code, datasets, or benchmark results, and lists specific filters (ML task, dataset, framework, stars). It distinguishes itself from siblings like find_benchmark_results by focusing on code/dataset links.

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 when to use (when needing papers with code), but does not explicitly mention alternatives or when not to use it. No comparative guidance against sibling tools like search or find_benchmark_results is provided.

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 fully discloses the HyDE technique, the symmetric-by-construction grouping in 'fast' mode, the resulting artificial balance of supporting/contradicting counts, and potential misclassification. With no annotations provided, the description carries the full burden and does so comprehensively without contradiction.

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 with the purpose first, then mode details, then parameter notes. It is comprehensive but slightly long; however, every sentence adds necessary value, so only minor conciseness improvement is possible.

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 7 parameters and no output schema, the description covers all essential behavioral aspects: mode caveats, limit per group, run_id attribution, and selfContained flag. The complexity of the HyDE-based classification is fully explained, making the tool complete for agent understanding.

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?

Although schema coverage is high (71%), the description adds significant contextual meaning beyond the schema, especially for 'mode' (explaining the retrieval and classification process in both modes), 'run_id' (its attribution purpose and requirement), and 'selfContainedOnly' (safety context).

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 pair ('Fact-check or substantiate a claim against the corpus') and clearly distinguishes the tool from siblings like 'find_related' or 'search' by focusing on evidence classification into supporting/contradicting/neutral groups.

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 use cases are given ('fact-verification, controversy mapping, 'is this claim known?' queries') and a detailed warning explains when 'fast' vs 'deep' mode should be used, including a critical caveat about balanced counts in 'fast' mode that prevents misinterpretation.

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?

No annotations provided, so description fully covers behavior: LLM-classified chunks, JOIN with benchmark results, extra LLM extraction step for detail parameter, and attribution requirements for run_id. 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?

All sentences are informative and necessary, no redundancy. Front-loaded with main purpose, then specifics, then caveats. Efficiently structured.

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

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

For a 10-parameter tool with no output schema, the description adequately explains return structure (method name, key idea, dataset, performance metric), covers edge cases (toy examples), and mentions benchmark JOIN. Complete for its complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context by explaining the extra LLM step for detail and the run_id attribution mechanism, providing value 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 it finds methodology approaches for a research task, returns structured method-level results, and distinguishes itself from sibling tools like search and methodist by specifying when to use it instead.

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

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

Explicitly states when to use (want HOW rather than papers) and when not to (not for conducting own research, use methodist instead), plus provides filtering advice and caveats about toy examples.

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?

Without annotations, the description discloses behavioral traits: mode-specific behaviors (e.g., byEntity biases), default values, and output detail levels. It does not cover permissions, rate limits, or error conditions, which prevents a higher score.

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-loading the purpose and mode distinctions, and includes all necessary information in a single paragraph. Slightly dense but efficient.

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 10 optional parameters and no output schema, the description covers mode differences, return format, and mentions no follow-up call needed. It lacks pagination or error details, but is sufficiently complete for typical use.

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

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

With 90% schema coverage, the description adds value beyond the schema by explaining behavioral nuances (e.g., mode details, run_id attribution rationale) and providing context that helps agents select parameters correctly.

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 finds related papers (not claims), specifies three modes, and explicitly distinguishes from the sibling tool find_related_claims, providing a specific verb and resource.

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 guidance: it is for papers, not claims, and directs users to find_related_claims for claim-related queries. However, it lacks explicit when-not-to-use or exclusions for other sibling tools like search_keyword.

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

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

Despite no annotations, the description discloses detailed behavioral traits: scoring field meanings, similarity agreement semantics, ownership handling, same-as cluster behavior, and linking instructions. This fully compensates for the lack of 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 long but well-structured with clear sections and bullet-like formatting. It front-loads the purpose and each sentence contributes necessary detail for a complex tool.

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

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

Given 8 parameters, no output schema, and no annotations, the description thoroughly explains all relevant aspects, including result fields, edge cases, and usage constraints. It is complete for an agent to effectively invoke and understand the tool.

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

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

Adds meaning beyond the input schema for parameters like vector, min_score, and run_id. However, parameters limit and claim_id are not elaborated, and 75% schema coverage already provides baseline meaning.

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 is an 'Association search over published claims' that finds related claims by example, using the claim's own stored vector. It distinguishes itself from the sibling methodist_search_semantic, which searches by free text.

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 specifies when to use: before creating a claim, when building on prior work, and at cycle closeouts. Also states it is read-only, never merging or writing, guiding against using it for mutations.

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?

No annotations are provided, so the description carries the full burden. It mentions 'Direct PG fetch — no vector search latency' but does not explicitly state read-only behavior, error handling, or authentication needs. The schema parameter descriptions add some behavioral context, but the main description lacks comprehensive disclosure.

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 two sentences, front-loading the purpose and usage. Every sentence adds value with no redundancy. It is appropriately sized and well-structured.

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 provides usage context and performance note, but lacks information about the return value (no output schema). Given the complexity (9 parameters), the description should be more complete. It does not explain what the response looks like or how to interpret results.

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

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

Schema description coverage is 89%, so the schema already documents parameters well. The description mentions filters (content type, section, entity mention) but does not add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Retrieve specific chunks from a known document with filters', indicating the verb (retrieve), resource (chunks), and context. It mentions specific filters but does not explicitly differentiate from sibling tools like get_document, though the name and context imply the difference.

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 says 'Use after search or find_methodology returned a relevant paper and you want more chunks from it without re-running search', providing clear when-to-use guidance. It does not mention when not to use or alternatives, but the context is sufficient.

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?

With no annotations, the description fully carries the transparency burden and excels. It discloses the default metadata-only behavior, explains the two independent availability axes (indexingTier and sourceAccessibility) with special handling for 'reindexing' including a stale-chunks warning, marks canServeFile as deprecated and not a content-availability signal, and clarifies that identifiers resolve to a fixed version rather than a mutable state. These are critical behavioral traits that go far beyond what a schema could convey.

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

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

The description is longer than typical, but every sentence contributes essential context given the tool's complexity. It is front-loaded with the core purpose and then layers in availability semantics. The prose could be slightly more structured (e.g., separated sections for the axes), but it remains dense and useful without fluff.

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

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

There is no output schema, so the description must compensate by explaining return-related concepts. It does so by naming the key metadata fields, chunkCount, sourceUrl, and the availability axes, and by explaining how to interpret them. Combined with the detailed parameter semantics and usage guidance, the description is complete enough for an agent to use the tool correctly across a wide range of scenarios.

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?

While schema coverage is high (89%), the description enriches parameter understanding by explaining interactions: includeChunks default changed in v2, chunkContentTypes implies includeChunks and includes unknown chunks as a fallback tier, chunkOrder='importance' requires searchId and falls back otherwise, and run_id is explained with a rationale. This adds context beyond the schema's individual field descriptions, although the schema already covers most parameter syntax.

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: 'Retrieve full paper details by ID.' It immediately disambiguates between metadata-only and chunk retrieval, and explicitly names get_chunks as the alternative for section-level content, distinguishing this tool from its siblings. The default behavior is clarified, so there is no ambiguity about what the tool does.

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 explicit decision rules: use get_chunks when indexingTier='full', fetch sourceUrl when sourceAccessibility permits, and resort to get_document for metadata and chunk retrieval. It also advises preferring filtered chunk retrieval over a full chunks dump for long papers and names get_chunks as the alternative for specific sections. This gives the agent clear when-to-use versus when-not-to-use 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?

With no annotations, the description adequately discloses behavioral details: it lists all possible status values and explains their meanings, including retryable vs terminal states. It also clarifies the optional run_id parameter's attribution behavior.

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

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

The description is succinct: a single sentence stating the purpose followed by a well-formatted status reference list. Every line adds value, and the key information is front-loaded.

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?

Despite lacking an output schema, the description sufficiently explains the expected return (a status string) by enumerating all possible values. It could mention that the response likely contains additional fields (e.g., timestamps), but the status list is thorough enough for the tool's core function.

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

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

Schema coverage is 100% (both parameters have descriptions). The tool description adds no additional meaning beyond the schema for document_id, but the run_id description in the schema is already detailed. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Check the processing status of a submitted document.' It lists all possible statuses with detailed explanations, and the function is distinct from sibling tools like get_document or search tools.

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

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

No explicit guidance is provided on when to use this tool versus alternatives (e.g., get_document for full document info). The description does not mention when not to use it or suggest 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?

No annotations provided, so description must cover behavioral traits. It discloses return fields and tier differences but does not mention permissions, rate limits, or side effects. Partial transparency.

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 succinct sentences: first covers purpose and return values, second adds tier nuance. No waste, front-loaded with essential info.

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

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

No output schema, but description explains return values (spam verdict, novelty, etc.) and tier behavior. With 2 params and simple return, it is adequately complete. Lacks only behavioral details like read-only confirmation.

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

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

Schema coverage is 100%, baseline 3. Description adds value: documentId is linked to submit_document.core_document_id, run_id has detailed attribution context. Provides 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?

Clearly states 'Read the content-review report for one of your own documents' – a specific verb and resource. Distinguishes from siblings like get_document, get_document_status, and get_my_documents, which serve different purposes.

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

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

Implies ownership ('for one of your own documents') and mentions tier-dependent behavior, but no explicit when-to-use, when-not-to-use, or alternatives. Lacks guidance relative to other 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?

With no annotations, the description partially covers behavior by scoping to user's own submissions and detailing statuses. However, it omits information about pagination, default ordering, rate limits, and the fact that it only returns documents from the authenticated user. This leaves gaps in understanding.

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

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

The purpose is front-loaded in the first sentence, but the lengthy status table makes the description verbose. While the table is useful, a more concise format could improve readability without losing 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 tool's low complexity (no output schema, simple parameters), the description covers the primary function and explains the status filter. However, it lacks guidance on when to use it over siblings and does not mention output formatting or pagination behavior, leaving the agent underinformed.

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

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

Schema coverage is 100%, but the description adds significant value by providing a detailed status reference for the status parameter. The descriptions for limit and run_id are already adequate in the schema, so the overall added value is above average.

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 ('List'), the resource ('documents'), and the scope ('you have submitted through OpenArx Portal'). This directly distinguishes it from sibling tools like search or get_document.

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 a detailed status reference that aids in using the status filter, but it does not explicitly explain when to use this tool versus alternatives like get_document_status or search. Context such as comparison with sibling tools is missing.

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?

Without annotations, the description carries full burden. It mentions 'live' statistics and '0 credits', giving some behavioral insight. However, it lacks details on side effects, rate limits, or response format. This is adequate but not comprehensive.

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 extremely concise: a single sentence plus a tagline. It front-loads the purpose and provides compact yet sufficient detail. 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 the tool's purpose and key statistics. For a simple, read-only stats tool with no output schema, it is fairly complete. Minor gaps: no mention of return structure or error conditions, but these are not critical given the tool's simplicity.

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

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

Schema description coverage is 100% with a detailed explanation of the 'run_id' parameter. The tool description adds no additional parameter meaning beyond listing general statistics. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Get' and resource 'live OpenArx platform statistics', listing specific examples (documents indexed, pipeline status, etc.). It effectively distinguishes itself from sibling tools, which are primarily for search, document management, and methodology, with no other statistics-focused tools.

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

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

The description provides no guidance on when to use this tool versus alternatives, when not to use it, or any prerequisites. The only extra note is 'Free (0 credits)', which implies cost but does not constitute usage guidelines.

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?

Describes the process: works out research type, hands methods stage by stage, reviews submissions, controls publishing, and emphasizes it never does the work. No annotations provided, but description compensates fully.

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 'START HERE' and efficiently structured, but slightly wordy. Every sentence adds value, though could be trimmed.

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

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

Given the tool's complexity and lack of output schema, the description covers purpose, usage, behavior, and alternatives comprehensively.

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

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

Schema coverage is 100%, so baseline 3. The description adds no additional meaning beyond the schema's parameter 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 it's a step-by-step scientific method guide for conducting research, distinguishing it from literature-search tools. The verb 'DIRECTS' and resource 'research process' are specific.

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 says 'START HERE with your research question' and instructs not to use for finding methods in existing papers, referencing literature-search tools as 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?

With no annotations, the description carries full burden. It discloses that escalation returns a ticket and that resolution is received later, but it does not mention whether the operation is destructive, authorization needs, or side effects. The term 'standing right' and 'inv-5' add some context but are vague.

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 at two sentences, front-loaded with the main action. It could be more structured but is not overly verbose.

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 no annotations, no output schema, and only partial parameter documentation, the description is incomplete. It does not cover prerequisites, return format specifics, error handling, or detailed behavioral 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 coverage is only 33% (only class has a description). The tool description does not explain any of the three parameters (class, detail, run_id) beyond what the schema provides. It fails to compensate for the low 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 the tool's purpose: escalating above the methodist (PM/human). It mentions the right to escalate and the output being a ticket with resolution via checkpoint or get_my_development. However, it does not explicitly distinguish it from other methodist tools, though the name itself is distinctive.

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 needing to escalate over the methodist, but lacks explicit guidance on when to use this tool versus alternatives or when not to use it. There is no comparison with sibling tools.

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

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

No annotations are provided, so the description carries full burden. It reveals that it does keyword match on claim text, searches claims not papers, and is scientific-only. However, it does not disclose behavioral traits like result format, pagination, or rate limits. The description adds some context but is not rich.

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

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

Two sentences, front-loaded with key purpose, no wasted words. Every sentence earns its place.

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

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

No output schema is provided, so the description should explain what the agent receives. It mentions pairing with methodist_find but does not describe the return shape. For a graph exploration tool, this is a gap, but the description is adequate for deciding to use it.

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

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

Schema description coverage is 33% (only run_id has a description). The description compensates for run_id with detailed attribution context, but does not add semantics for 'topic' or 'limit' beyond their types and constraints in the schema. Baseline 3 is appropriate as the description adds partial value.

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

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

The description clearly states the tool explores a topic across published claims in the layer-2 knowledge graph using keyword match, and distinguishes from the sibling 'explore_topic' which operates on papers. The verb 'explore' and resource 'claims' are specific.

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 explicit context: when to use this tool (scientific-only, lightweight entry into the graph) and an alternative ('for the conceptual landscape of the PAPER corpus use explore_topic'). It also mentions pairing with methodist_find. However, it does not explicitly state when not to use it.

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

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

With no annotations, the description carries full burden and discloses important behaviors: process nodes excluded, default relation set, direction parameter clarification, and run_id ownership validation. It does not cover pagination or rate limits, but overall transparency is good.

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 dense paragraph but front-loads purpose and efficiently covers key details. It could be slightly more structured with bullet points, but every sentence is informative and no words are wasted.

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

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

Given the complexity (7 parameters, no output schema), the description adequately explains purpose, defaults, and parameter nuances. It conceptually describes the output (relations and connected records), though it lacks explicit return format details. Still, it is sufficiently complete for effective use.

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

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

Schema description coverage is high (86%), so baseline is 3. The description adds value beyond the schema by clarifying the direction parameter's distinct meaning and explaining run_id attribution. This extra context justifies a score of 4.

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 finds scientific records related to a claim via relations, specifying scientific-only and excluding process nodes. It distinguishes from siblings by detailing the default epistemic relation set and the option for engineering relations, making it distinct from related tools like find_related_claims.

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

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

The description explains default behavior and how to customize with relation_class, but does not explicitly state when to use this tool versus alternatives like find_evidence or find_related_claims. However, it provides clear context for its use within the methodist family.

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?

With no annotations, the description carries full burden; it discloses that process records are never exposed and process-referencing fields are stripped, adding important behavioral context.

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

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

Two sentences, front-loaded with purpose, each sentence adds value; no extraneous 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?

Covers what is fetched and excluded; could mention error handling or response shape, but adequate for a simple fetch tool with no output 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?

Schema coverage is 50% (id undocumented, run_id well-described); the description adds no additional parameter meaning beyond the schema, failing to compensate for the lack of id documentation.

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 a scientific record by id, specifies the record types (claim/relation/activity/metric/bundle), and explicitly excludes process records, distinguishing it from siblings.

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

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

Implied usage (fetch by id), but no explicit comparison with sibling tools like methodist_find or methodist_search; no when-not-to-use 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?

States 'Deterministic — no model call' which indicates no mutation and predictable behavior. However, no annotations are provided, so description carries full burden; lacks details on side effects, permissions, or error conditions.

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

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

Two sentences with no wasted words. Action verb and result summary are front-loaded.

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 tool with one parameter and no output schema, the description covers purpose and predictability but fails to explain the parameter or provide usage 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?

Single parameter run_id is not described in schema (0% coverage) and the description does not explain what run_id represents, any constraints, or expected format.

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?

Clearly states it returns the run's current dose, stage, and status, with a helpful parenthetical 'where am I'. Distinct from siblings like 'methodist_find' or 'methodist_get' by focusing on current state.

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 vs alternatives like 'methodist_get' or 'methodist_traverse'. Does not mention prerequisites or 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?

With no annotations, the description must disclose behavioral traits. It only describes the output data, not whether the tool is read-only, requires authorization, or has side effects. The read-only nature is implied but not explicit.

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?

Single sentence with no wasted words. Some phrasing is dense but still clear. Front-loading is good (purpose first).

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 parameterless tool, the description gives a reasonable overview of the output. However, lacking output schema leaves uncertainty about the data structure. Adequate but not 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?

No parameters exist, so schema description coverage is 100%. The description adds meaning by explaining the tool's output, which goes beyond the empty 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?

Description clearly states it provides the mentee's development view with specific components (autonomy, passed units, tier, corrections). It distinguishes itself from sibling tools by focusing on 'my development', but does not explicitly differentiate from other methodist tools.

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

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

No guidance on when to use this tool versus alternatives. The description does not mention prerequisites, context, or exclusions. Given many sibling methodist tools, this is a significant gap.

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?

Discloses key behavior: pauses the run and records the need. But no annotations exist, and description omits side effects, reversibility, or post-pause state.

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

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

One sentence of 15 words, front-loaded with verb and resource, 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?

Adequate for a simple two-param tool, but missing context on how pausing works, how to resume, and what the recorded need entails. No output schema, so return value is undefined.

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?

0% schema description coverage, yet description only hints at 'need' parameter (e.g., missing access/resource) and fails to explain 'run_id'. Does not sufficiently compensate for schema gaps.

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?

Description clearly states verb 'Report' and resource 'blocking need', with an example. It differentiates from siblings by specifying 'pauses the run', but could be more precise about what constitutes a blocking need.

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

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

Implies usage for blocking issues, but no explicit when-to-use or alternatives among siblings. No guidance on prerequisites or when not to use.

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?

With no annotations, the description carries full burden. It discloses that process records are never returned, relation_class defaults to epistemic, and run_id attribution behavior. It does not explicitly state read-only or safety, but search tools are generally safe; 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?

The description is three sentences, concise and front-loaded with the primary purpose. Every sentence adds value with no 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?

For a tool with 7 parameters and no output schema, the description covers main functionality and key behaviors (process exclusion, relation_class defaults, run_id attribution). However, it does not describe the return format or pagination, which are important for a search tool given no output 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?

The description adds meaning beyond schema: explains the purpose of kind, relation_class, and run_id in detail. It clarifies the default behavior for relation_class and the run_id attribution logic. However, some parameters like limit and subtype are not additionally explained beyond 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 performs keyword search over the scientific graph across multiple kinds (claim/relation/activity/metric/bundle), and distinguishes it from methodist_search_semantic for semantic search. It also mentions that process records are excluded, further clarifying 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?

The description provides specific guidance: when searching relations, the default is epistemic set; pass relation_class for engineering/all. It also notes that for semantic search over claims, use methodist_search_semantic. However, it does not explicitly state when to avoid this tool entirely.

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?

With no annotations provided, the description carries full burden. It discloses the search behavior (semantic, based on embeddings), scope mechanics (e.g., 'engineering-projected vector'), and run attribution. It also states 'a text-similar non-engineering claim never leaks in', adding confidence. However, it does not explicitly state that the tool is read-only (no side effects), which would be beneficial for a mutation-averse agent.

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 dense paragraph, but every sentence adds value. It could be broken into separate sentences or bullet points for easier parsing, but it remains concise and informative without 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 7 parameters and no output schema, the description covers return fields (claim ids, similarity scores, text snippet) and explains the two scopes thoroughly. It also covers run_id usage. It does not explain 'engineering-projected vector' nor the '§7.6 identity-canonical' in detail, but these are domain-specific terms that may be assumed. Overall, it provides sufficient context for an agent to invoke the 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?

Schema description coverage is 71% (5 of 7 params have descriptions in schema). The description adds meaning beyond schema for 'scope' (explains default and detailed behavior) and 'run_id' (context about attribution and run-anchored property). For 'collapse_same_as', it clarifies the representative selection. The remaining params (limit, query) are simple types and schema descriptions suffice.

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 performs semantic search over methodist-published claims, distinguishes two scopes (scientific vs engineering), and specifies return fields (claim ids, similarity scores, text snippet). This differentiates it from sibling tools like 'methodist_search' or 'search_semantic'.

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

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

The description explains when to use scientific scope (default, §7 claim space) vs engineering scope (reuse-discovery) and provides context for run_id attribution. However, it lacks explicit guidance on when NOT to use this tool versus alternatives like 'methodist_find' or 'explore_topic', so it's not a full replacement for sibling differentiation.

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?

With no annotations, the description fully bears the responsibility of behavioral disclosure. It clearly separates record values from edge labels, cautions about the overloaded 'direction' term, explains traversal direction semantics, mentions the validator's accepted edge labels, and notes the extra 'cycle_detected' return for engineering. This goes well beyond basic expectations.

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

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

The description is dense but every sentence carries unique value. It is front-loaded with the core purpose, then systematically addresses edge cases, naming traps, and the validation constraint. The use of '★' highlights critical warnings without redundant phrasing. Length is justified by the tool's 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 covers behavior, parameter semantics, and pitfalls thoroughly. The only gap is that it does not explicitly describe the standard return structure (e.g., list of nodes/edges, ordering, or whether it returns the path). It mentions cycle_detected only for engineering, leaving the default epistemic return shape assumed. Given the lack of an output schema, a brief note on return format would make it fully complete.

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

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

Although schema covers 83% of parameters, the description adds substantial meaning beyond the schema: it explains the default/max hops behavior, clarifies the direction enum's real-world meaning, distinguishes relation_class values, and details the run_id attribution requirements. It even warns about common user errors, making parameter usage far clearer.

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 and resource: 'Multi-hop traversal from a claim over typed relation edges of ONE class.' It immediately distinguishes the two relation classes (epistemic §7 vs engineering), and relates to the broader methodist context. This is unequivocal and differentiates from sibling tools.

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

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

It explains when to use each relation_class: default epistemic for §7 support/extend/qualify/refute/background/shared_evidence/same_as, and engineering for depends_on/satisfies. It also warns against writing edges and confusing direction. However, it does not explicitly contrast with alternative tools (e.g., methodist_find or search), so the usage guidance is strong 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?

No annotations provided. Description discloses cache duration and non-re-run nature, but lacks details on side effects, rate limits, or auth requirements. Adequate but not rich.

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 concise sentences, front-loaded with purpose, no unnecessary words. Efficiently communicates key 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?

Covers purpose and cache constraint. Missing response structure hints and error cases, but sufficient for a simple pagination tool with well-described 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?

Schema has high coverage (75%+), describing all parameters. Description adds context for searchId and offset but no significant new meaning beyond schema. Baseline 3.

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?

Clearly states the tool continues a previous search without re-running, using searchId and offset. Distinguishes from sibling search tools which initiate new searches.

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 says when to use (after a search, to get more cached results) and when not (cache expired over ~30 min, re-run original tool). Provides clear alternative.

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

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

With no annotations, the description discloses critical behaviors: only own agent-created drafts can be published, publishing is the billable event, returns indexing status and IDs, and lists specific error types. It also mentions unrecognized metadata keys are dropped. It could mention if the action is irreversible, but overall is transparent.

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 roughly 5 sentences and front-loads the main purpose. It is concise but could be slightly more compact; still, every sentence adds essential 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 complexity (3 params, nested metadata, no output schema), the description explains the return format (indexing status + IDs), error cases, and relationship to create_draft. It also covers metadata handling and run_id provenance. This is complete for an agent to use the 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?

Although schema description coverage is 100%, the description adds significant value: draft_id must be from own account and create_draft; metadata keys like COI/license/title are required at publish; run_id attribution and provenance check are explained. This goes well beyond the 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 verb 'publish' and the resource 'one of YOUR OWN Portal drafts', distinguishing it from siblings like create_draft (which creates drafts) and submit_document (which submits full documents). It specifies the scope and the source of drafts.

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 states when to use: when you have a draft created with create_draft. It also states what is rejected (someone else's draft, human-staged, non-existent). However, it does not provide explicit alternatives or when not to use, though the context implies it's the only way to publish drafts.

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 the hybrid search behavior and support for exact terms (paper IDs, author names), which is useful. However, there are no annotations, so the description carries the full burden for behavioral transparency. It does not mention that the tool is read-only, any rate limits, or important coverage caveats like the vectorModel space limitation (which is only in the schema, not the description). Thus, it is adequate but has clear gaps.

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 sentences long, front-loaded with the core purpose, and every sentence adds value. The first sentence explains what the tool does, the second enumerates filtering capabilities, and the third gives usage guidance with named alternatives. There is zero redundancy or filler.

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

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

For a tool with 14 parameters and many sibling tools, the description provides enough context to decide when to use it: it states the hybrid nature, default status, and key filters. It does not explain the fast/rerank strategy or run_id attribution, but those are detailed in the schema. Given no output schema, the description is reasonably complete for decision-making, though not exhaustive.

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 100% parameter description coverage, so the baseline is 3. The description mentions filtering by content type, entities, categories, and date range, which map to existing schema properties but add no new semantic meaning beyond what the schema already provides. Therefore, the description does not significantly enhance parameter understanding beyond the structured schema.

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

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

The description states the tool's function with a specific verb and resource: 'Hybrid semantic + keyword search across scientific papers.' It explicitly mentions combining vector similarity with BM25 full-text matching, and distinguishes it from sibling tools by calling it the 'Default mode for general queries.' This clearly sets it apart from search_keyword and search_semantic.

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 says when to use this tool ('Default mode for general queries') and provides direct alternatives: 'use search_keyword for exact-term lookups or search_semantic for pure paraphrase queries.' It also lists supported filtering dimensions, giving the agent concrete guidance on when this tool is appropriate versus its siblings. This meets the highest bar for usage 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?

No annotations exist, so description fully carries the burden. It clearly explains the tool uses BM25 algorithm, does not use semantic vectors, and describes ranking behavior (chunk-level term frequency). It also notes the limitation of surfacing frequent-term papers over canonical sources. While lacking details on authentication or rate limits, it provides sufficient behavioral context for an agent.

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 paragraph that front-loads the core purpose. Every sentence adds value (e.g., 'Does NOT use semantic vectors', explicit alternatives). No redundancy or filler. Length is appropriate 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?

Given the tool has 12 parameters (mostly optional) and no output schema, the description thoroughly explains each parameter's behavior, the underlying algorithm, and relationship to sibling tools. It covers when to use, how to use, and potential pitfalls (e.g., BM25 not guaranteeing canonical results). The description feels complete for an AI agent to make an informed decision.

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

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

Schema coverage is 100%, so baseline 3 applies. However, the description adds significant context beyond the schema: for 'query' it explains BM25 ranking and alternative tools; for 'detail' it enumerates content levels; for 'run_id' it clarifies attribution; for 'entities' it describes soft filtering and legacy handling. This extra value justifies a 4.

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?

Description starts with 'Pure keyword (BM25) search — fastest option, optimal for exact-term lookups' and lists specific use cases (paper titles, author names, method names, arXiv IDs). It distinguishes itself from siblings by explicitly stating it does not use semantic vectors and directing users to alternatives for conceptual queries.

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: 'Use this when you know the specific term you're looking for. For paraphrased or conceptual queries, prefer "search_semantic" or "search".' Additionally, the query parameter description warns about BM25 behavior and when to prefer find_by_id for canonical 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?

No annotations are provided, so the description carries the burden. It clearly discloses the core behavioral trait — dense vector similarity using Gemini or SPECTER2 — and the decision to skip BM25 fusion to avoid term-matching noise. However, it does not mention material limitations like the SPECTER2 coverage gap (which is only in the parameter schema) or return/pagination 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?

Three sentences, front-loaded with purpose, followed by usage guidance and alternatives. Every sentence earns its place with no repetition of schema details.

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 rich 100%-covered schema that documents all 14 parameters, the description provides the missing context: tool selection, embedding behavior, and when to prefer siblings. No output schema exists, but the detail parameter covers output granularity, so the combined schema+description is highly 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 100%, so the baseline is 3. The description adds some conceptual meaning (e.g., 'paraphrased queries' aligns with the query parameter), but most parameter semantics are already fully documented in the schema, including the important vectorModel coverage warning.

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 'Pure semantic (vector) search', a specific verb+resource that immediately states the tool's function. It further distinguishes from siblings by naming 'search_keyword' and 'search' as alternatives for exact and mixed queries.

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 explicit guidance on when to use: 'best for paraphrased queries, concept exploration, "papers arguing X" type questions'. It also gives direct alternatives for other scenarios: 'For exact terms use "search_keyword". For mixed queries use "search".' This fully orients an agent to select the right 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?

With no annotations provided, the description fully discloses key behaviors: immutability of published documents, file-only content (no inline text), mutual exclusivity of content sources, limits, dry_run behavior (no charges, no commit), and the response structure. It covers all important traits for safe and effective use.

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, starting with the main purpose and then detailing content options, limits, and dry_run. It is front-loaded and avoids redundancy, though it could be slightly more concise given its length. Overall, it efficiently conveys necessary information without waste.

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 27 parameters, no output schema, and 4 required fields, the description is highly complete. It covers the main output (core_document_id), validation behavior, interactions with create_upload_url, and all constraints. An agent has sufficient information to use the tool correctly without external references.

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?

Despite 100% schema coverage, the description adds significant value beyond the schema: it explains the purpose of each parameter, the mutual exclusivity of content_archive_base64 and content_ref, preferences for content upload method, detailed limits, and the dry_run response format. This greatly aids correct parameter selection and usage.

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 'Submit a document for indexing on OpenArx,' which is a specific verb and resource. It distinguishes from sibling tools like create_upload_url by noting when to use the latter for large content. The supported formats and returned core_document_id are mentioned, making the 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?

The description provides clear guidance on when to use create_upload_url for large files, when to set dry_run for validation, and how to handle updates via new versions. However, it does not explicitly contrast with all siblings (e.g., create_draft, publish_draft), leaving some selection context implicit.

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