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 are provided, so the description carries the full behavioral burden. It goes well beyond the schema by disclosing the layer-2 claim graph exclusion, the cluster-with-representative-chunks output shape, the LLM-extracted keyConcept diversification mechanism, the temporal ordering bias toward recent papers, and the single-paper dominance protection via maxClustersPerPaper. This is strong behavioral 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?

The description is front-loaded with the core purpose and each section adds distinct value. It is slightly repetitive in contrasting 'ranked list' with 'conceptual clusters' twice, and the keyConcept sentence is a bit dense, but overall it is compact for the amount of behavioral and usage context it provides.

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 complex discovery tool with 9 parameters and no output schema, the description covers the important non-schema aspects: scope, output type, use cases, alternatives, temporal bias, and diversification behavior. An agent has enough context to decide when to invoke it and to set date/maxClustersPerPaper meaningfully without needing additional explanation.

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 already high at 78%, so the baseline is 3. The description adds genuine value beyond the schema by explaining how to use dateTo/dateFrom for temporal slicing and how maxClustersPerPaper affects cluster diversity and paper dominance. Other parameters like concept, clusterCount, categories, and vectorModel are adequately covered by schema descriptions, though the prose does not add extra nuance for them.

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

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

The description uses a specific verb ('Map'), names the resource ('the paper corpus'), and clearly contrasts itself with sibling tools: it searches papers and chunks, not the claim graph, and returns conceptual clusters rather than a ranked list. This distinguishes it from methodist_explore_topic and search without needing to inspect sibling schemas.

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 the tool ('what approaches exist to X' queries, breadth over depth) and when not to (for published claims, use methodist_explore_topic). It also gives concrete temporal guidance: specify dateTo for historical exploration and dateFrom+dateTo to slice a specific era, which is actionable routing and usage advice.

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?

With no annotations provided, the description carries the full burden — and it excels. It discloses the HyDE mechanism, the critical 'symmetric-by-construction' flaw in fast mode (counts are 'approximately balanced BY CONSTRUCTION and do NOT reflect actual literature distribution'), misclassification risks with a concrete example, and hard cost/latency data ('one LLM call PER CHUNK, up to ~60 per invocation,' 'median 52 s end-to-end'). This is unusually candid about failure modes and resource implications.

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 earns its place: purpose, method, classification output, use cases, then the two modes with the critical caveat flagged by 'IMPORTANT.' It is front-loaded with the core purpose before any mechanism detail, and the fast/deep contrast is structured so the caveat is unmissable. For a tool with this behavioral complexity, the length is justified rather than padded.

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

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

For a complex 7-parameter tool with no output schema and no annotations, the description covers a remarkable amount: core semantics, HyDE mechanism, mode selection, the statistical caveat, cost/latency, and the selfContained return indicator. The main gaps are the two undocumented parameters (detail, categories) and the absence of a return-structure description beyond 'returns chunks with selfContained flag,' which a full output schema would have covered. These are meaningful but minor against the strong coverage.

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 71%, above the low threshold, so the schema carries most of the parameter documentation burden. The description adds useful context for selfContainedOnly by explaining the selfContained flag as a 'safe-to-cite indicator' and enriches claim semantics. However, two parameters (detail and categories) are entirely undocumented in both schema and description, and the description adds no meaning for limit or run_id beyond what the schema already provides.

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 immediately adds the distinguishing behavior: 'retrieves and CLASSIFIES evidence into supporting / contradicting / neutral groups.' This clearly separates it from sibling retrieval tools like search, find_related, and methodist_find, which do not classify evidence into stance 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?

The description gives explicit when-to-use context: 'Use for fact-verification, controversy mapping, 'is this claim known?' queries,' plus mode-level routing ('Use 'deep' when measuring controversy balance, literature distribution...' and 'Use fast mode for 'is there evidence on either side?', not for 'how is the field actually split?''). It stops short of naming sibling alternatives and stating when NOT to use this tool versus them, so exclusions are only implied rather than explicit.

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

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

Annotations are absent, so the description carries full burden. It discloses non-obvious behavior: results are structured method-level aggregates built from LLM-classified methodology chunks joined with benchmark results, and it honestly warns that toy-example mentions can surface. This helps an agent anticipate precision issues before invoking the 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 front-loaded with the core purpose and each sentence carries useful information about output, data source, caveats, or sibling routing. It is slightly verbose due to restating filter concepts and a long final exclusion, but it remains efficient and well-organized.

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 10 parameters and no output schema, the description covers return fields, data provenance, a precision caveat, and the relationships to key siblings. Detailed parameter behavior is left to the schema, which is acceptable, but a concrete return example or pagination note 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?

Schema description coverage is 100% and each parameter already has rich detail (examples, defaults, enum semantics including the ~1.5s overhead for detail). The description only summarizes filters at a high level and does not add meaning beyond the schema, so the 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?

States a specific verb and resource ('Find methodology approaches for a specific research task') and describes the structured output: method name, key idea, dataset, performance metric. It additionally distinguishes itself from generic `search` and from the `methodist` door, so an agent can place it precisely among 35 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?

Explicitly provides selection criteria: 'Use this instead of `search` when you want HOW researchers approach a problem rather than 10 papers about it.' It also names the exclusion case, directing users to `methodist` for step-by-step research guidance, and advises category filtering to narrow scope.

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?

With no annotations provided, the description carries the full transparency burden. It clearly states the tool is read-only, never merges or writes, explains the meaning of ownership, verification status, same_as collapsing, and link-target following, and cautions about ambiguous links. This is excellent behavioral 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 excessively long and repetitive, with dense run-on explanations and apparent typos (e.g., 'by-EXAMPLE sibling'). Important details are buried in a wall of text, making it harder to parse quickly. It would benefit from tighter organization and pruning.

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 having no output schema, the description thoroughly explains the semantics of the returned fields: per-space scores, similarity agreement, ownership, same_as canonical selection, linking behavior, and the separate verification_outcome field. This gives an agent enough context to correctly interpret results and avoid misuse.

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 75%, so the baseline is 3. The prose adds useful context for vector='both' and min_score semantics, but it does not describe limit or claim_id, which are missing from the schema. Overall it adds only modest value beyond the existing 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 identifies the tool as an association search over published claims and distinguishes it from semantic text search by noting this searches by the claim's own stored vector. It also gives concrete use cases (before creating a claim, building on prior work, cycle closeouts), making the purpose and differentiation explicit.

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 when-to-use scenarios and contrasts with methodist_search_semantic (free text vs. stored vector). It does not explicitly position itself against all sibling tools such as find_related or methodist_find, but the guidance is strong and actionable.

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 behavioral burden. It discloses a concrete execution trait ('Direct PG fetch — no vector search latency') and implies a read-only safety profile via 'Retrieve' and 'fetch'. It does not explicitly state non-destructiveness or describe the response shape, but the schema's parameter notes thoroughly document filter fallback and tier-ordering 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 short sentences, each earning its place: purpose, usage context, and a behavioral/performance note. Purpose is front-loaded, and nothing repeats schema content or pads the definition.

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 a rich, 100%-covered schema, the description covers the selection and invocation essentials: what it does, when to use it, and which filter parameters matter. The only gap is that no output schema exists and the description doesn't summarize the response shape, though schema parameter notes do reference response counts (strictMatchedChunks + unknownChunksIncluded).

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 baseline is 3. The description adds only a high-level filter taxonomy (content type, section, entity mention) that maps to contentType/section/entities. All deeper semantics — soft-filter tiers, unknown-chunk inclusion, chunkOrder fallback, run_id attribution — are already fully documented in the schema, so no compensation is needed.

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

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

States a specific verb+resource: 'Retrieve specific chunks from a known document' with explicit filter dimensions (content type, section, entity mention). The phrase 'known document' and the post-search framing clearly distinguish it from sibling search/find tools that discover documents rather than retrieve parts of an already-identified one.

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

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

Explicitly names the triggering context — use after `search` or `find_methodology` returned a relevant paper, when you want more chunks 'without re-running search' — which routes agents away from the obvious alternative. It stops short of listing exclusions or naming other alternatives like get_document (whole-document retrieval) or paginate, so a full when-not-to-use boundary 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?

With no annotations, the description carries the full burden and does so unusually well: it discloses the stale-chunk hazard during 'reindexing', clarifies that canServeFile is DEPRECATED and not an availability signal, and defines two independent availability axes. It also states the immutable-version semantics of an identifier, which is non-obvious 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?

Purpose and the default-vs-includeChunks distinction are front-loaded, and the dense detail is largely earned by the tool's complexity. It is still a very long single block with heavy ALL-CAPS emphasis, and parts of the availability-axis explanation are closer to response documentation than invocation guidance.

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

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

With no output schema, the description compensates by enumerating the default metadata fields and the availability fields an agent must interpret. The remaining gap is the unexplained 'detail' enum and no guidance on pagination limits beyond the offset/chunkLimit hints.

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 already 91%, so the baseline is 3, but the description adds real value on top: it explains why includeChunks defaults false, when to prefer filtered retrieval, and how the availability axes gate content access. The notable miss is the 'detail' enum (minimal|standard|full), which has no description in either the schema or the description.

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

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

Opens with a specific verb+resource ('Retrieve full paper details by ID') and immediately scopes the default behavior ('metadata only') and the escape hatch ('includeChunks=true'). It explicitly names the sibling get_chunks as the alternative for section-level content, so the agent can differentiate without opening either schema.

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

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

Gives explicit when/when-not routing: metadata by default, includeChunks for content, chunkContentTypes/section filters for targeted retrieval, get_chunks for section-level reads, and 'prefer filtered chunk retrieval over full chunks dump' for long papers. It also states the decision rule for reading content ('if indexingTier=full use get_chunks; else fetch sourceUrl').

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?

Without annotations, the description carries the transparency burden and does meaningful work: it discloses that results are scientific-only, that process nodes never appear, and that relations default to the epistemic §7 set with an explicit engineering/all option. It doesn't cover response shape or auth, but for a find-style read tool the main behavioral scoping is present.

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 dense sentences, no filler; the primary operation and key constraint are front-loaded. Every sentence adds semantic 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?

Given 10 parameters and no output schema, the description plus the rich parameter schema covers the invocation essentials: target identity, relation classes, and default/optional scoping. The main omission is explicit routing against overlapping siblings, but the behavior is specified well enough to call correctly.

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

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

Schema coverage is high (~90%), so the baseline is 3; the description adds modest value by identifying `from_id` as a claim and enumerating the default epistemic relation set, which the schema's `relation_class` description only summarizes. It does not need to restate the already-detailed parameter docs.

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

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

The opening phrase 'Find scientific records related to a claim by its relations' is a specific verb+resource statement, and it adds scope details ('relations touching it + connected records', 'process nodes never appear'). It does not explicitly name sibling alternatives such as find_related or methodist_traverse, so it stops short of a 5.

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

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

The description gives clear use context: call when you need scientific records connected to a claim through relations, and it states the epistemic default and how to opt into engineering edges. It does not spell out when-not-to-use or point to sibling tools, but the context is not merely implied.

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

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

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?

With no annotations, the description carries the full burden, and it does disclose one genuinely useful behavioral fact: state is DERIVED from support/refute relations and never stored. Beyond that it says nothing about read-only semantics, permissions, or result size/pagination, leaving notable gaps for a tool with zero annotation coverage.

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 compact sentences, front-loaded with the outcome and then the derivation rule. The closing clause ('a claim's status is inside its identity') is more philosophy than operational guidance, but it is short and does explain why state is derived.

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 two-parameter read tool with no output schema and no annotations, the description does explain the return values and their semantics, which is helpful. It still omits question_id format, pagination, and any permission/auth notes, so it is adequate rather than 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 coverage is 50%: run_id is richly documented in the schema itself, while question_id has only a minLength. The description adds marginal meaning by implying question_id must reference an 'open question,' but it does not clarify format or the run-attribution requirement beyond what the schema already provides.

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

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

The description states a specific resource (hypotheses addressing a question) and the return payload (each hypothesis's state from a fixed four-value set). It is clear what the tool produces, but it never names or contrasts itself against sibling tools like methodist_hypothesis or methodist_find, so an agent must infer the boundary.

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

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

The phrase 'open question' hints at the triggering context, but there is no explicit when-to-use, when-not, or named alternative among the many methodist_* siblings. The agent is left to infer that this is the lookup for hypotheses tied to a specific question_id.

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 the description carries the full burden. It usefully discloses the returned content (falsifier, questions, relations, attestation provenance), which matters because there is no output schema, but it never states the operation is read-only, nor does it cover permissions or side effects.

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

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

A single front-loaded sentence that names the resource first and then the returned components. It is dense but every clause conveys content; no filler.

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

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

For a simple read-by-id tool with no annotations and no output schema, the description covers the return shape well enough to substitute for a missing output schema. However, it omits the read-only nature, the meaning of hypothesis_id, and any usage context, leaving gaps for a 2-parameter lookup.

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

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

Schema description coverage is 50%: run_id is richly documented in the schema, but hypothesis_id has no description anywhere. The description's 'One hypothesis' only weakly implies that hypothesis_id selects the record, so it does not compensate for the undocumented parameter.

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 identifies a specific resource (one hypothesis) and its scope ('in full'), enumerating the fields it returns (falsifier, questions, relations, attestations). It distinguishes itself implicitly from the plural sibling methodist_hypotheses_for_question via 'One hypothesis', though no explicit verb like 'fetch' or 'retrieve' is used.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative. The context of fetching a single hypothesis by id is only implied.

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

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

With no annotations, the description carries the full burden. It does disclose a genuine behavioral trait: a move whose hypotheses were all refuted is still included with its count, and it warns the read 'must not flatter' the methodology's unverified claim. That is useful semantic context, but the description never states that this is a read-only operation, says nothing about permissions, pagination, ordering, or return format.

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?

Only two sentences and the core purpose is front-loaded. The second sentence is dense and jargon-laden ('marks that claim unverified', 'must not flatter it'), which slightly hinders parsing, but nothing is 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?

There is no output schema, so the description should explain return values; it hints that moves appear 'with their count' but omits ordering, available fields, and result shape. For a read/analysis tool with one optional param and no annotations, this is adequate but leaves clear gaps.

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

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

Schema description coverage is 100% and the single run_id parameter is thoroughly documented in the schema (optional, attribution semantics, ownership rejection). The description adds nothing about parameters, so the baseline 3 applies.

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

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

The opening fragment 'Which generating moves produce hypotheses that survive' conveys the analytical question the tool answers, which is more specific than a tautology. However, it lacks an explicit verb or resource ('this tool returns/ranks moves by...') and does not differentiate itself from methodist-adjacent siblings like methodist_hypotheses_for_question or methodist_hypothesis. The purpose is inferable but vague in framing.

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

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

There is no statement of when to call this tool, no prerequisites, and no named alternatives among the many methodist_* siblings. The agent is left to infer usage entirely from the output-semantics sentence.

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 provided, the description carries the full burden and uses it well: it discloses the epistemic §7 default, the opt-in behavior for engineering edges, and the hard exclusion of process records. It stops short of describing result ordering or pagination, but for a read-style keyword search these are minor 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?

Four tight sentences with zero waste. The core verb+resource is front-loaded, and each sentence earns its place: scope, kind narrowing, relation defaults, process exclusion, and the semantic-search pointer.

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 7-parameter tool with no annotations and no output schema, the description covers selection criteria, the critical relation-class default, and a hard exclusion, while the run_id attribution requirement is fully covered in the schema. The only missing pieces are minor invocation details like result ordering and pagination.

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 genuine meaning beyond the schema for the two non-obvious parameters: kind (narrowing the search) and relation_class (default epistemic, engineering/all opt-in). With 57% schema coverage, limit, latest_only, and subtype receive no prose explanation, but their names are self-evident and run_id already has a rich schema description.

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

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

States a specific verb (keyword search), a defined resource (the scientific graph), and lists the supported record kinds (claim/relation/activity/metric/bundle). It explicitly distinguishes itself from methodist_search_semantic and adds a hard scope exclusion (process records are never returned), so an agent can differentiate it from sibling search tools without opening the schema.

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

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

Explicitly names methodist_search_semantic as the alternative for semantic search over claims and documents the default epistemic §7 relation set with the opt-in for engineering/all edges. It does not, however, draw boundaries against the other sibling search tools (search, search_keyword, methodist_find), leaving some selection inference to the agent.

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 responsibility for behavioral disclosure. It transparently explains the search mechanics (nearest claims, projection exclusions, no leakage for engineering), the output format (claim ids + similarity scores + snippet), and the run_id attribution behavior (must be the agent's own run, rejected otherwise). It also clarifies how claim_status_set expands and that collapse_same_as returns a best-matching face rather than the canonical ID. No contradictions with annotations (none present).

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 moderately long but tightly packed with necessary information. It opens with the core purpose, then explains scopes, then the return, then parameter-specific notes. Every sentence adds value; there is no fluff. It is slightly dense, but for a tool with eight parameters and two distinct modes, the length is justified. Not as short as the ideal 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 no output schema, the description covers the essential return content and the key behavioral details (scope handling, run_id constraints, collapse semantics). It does not explicitly mention pagination or limit behavior, but the limit parameter is documented in the schema and its effect (max 50) is straightforward. The description is sufficient for an agent to invoke the tool correctly in most scenarios, though a sentence on default ordering or pagination 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?

The schema description coverage is 75%, so the baseline is 3. The description adds meaningful context beyond the schema for several parameters: it explains scope semantics, run_id attribution and rejection rules, claim_status_set expansion and precedence over claim_status, and collapse_same_as behavior (best-matching face vs canonical). It does not elaborate on limit, query, latest_only, or claim_status, but these are relatively self-explanatory and the schema already documents them. The added value raises it to 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 states a specific verb and resource: 'Semantic (embedding) search over methodist-published claims — the nearest claims to a natural-language query.' It distinguishes the two scopes (scientific and engineering) and what each returns, making it clear what the tool does and how it differs from generic search. It also names the return content (claim ids, similarity scores, text snippet), further sharpening the purpose.

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 context for when to use each scope: scientific (default) for the §7 claim space and engineering for reuse-discovery of engineering approaches. However, it does not explicitly compare this tool to sibling tools like search_semantic or methodist_search, nor state when not to use it. The guidance is clear for scope selection but lacks alternative-based exclusion criteria.

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 is highly transparent about behavioral nuances: it clarifies traversal direction is not the record field, notes class label-spaces are disjoint, states every reached node carries is_superseded, and explains that superseded nodes are traversed intentionally. It also warns against writing and describes cycle_detected for engineering.

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 overly verbose and contains redundant or confusing meta-commentary, such as repeated warnings about label values and the awkward phrase 'This sentence used to name...'. Core information could be conveyed in half the length without losing meaning.

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

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

Given the absence of an output schema, the description does a good job explaining key output aspects like is_superseded and cycle_detected. However, it does not mention the default direction, nor describe result pagination or the full output shape, leaving some gaps for a complete caller.

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

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

The schema covers most parameters with descriptions, and the description adds meaningful context for from_id, relation_class, direction, and max_hops. It also clarifies the meaning of 'direction' in this read context and gives concrete enum examples.

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 multi-hop traversal from a claim over typed relation edges of one class. It distinguishes the two relation classes (epistemic and engineering) and the direction semantics, making the tool's purpose unambiguous even without explicit sibling comparisons.

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 some usage guidance, such as how to select relation_class, direction semantics, and that superseded claims are deliberately traversed. However, it does not explicitly say when to prefer this tool over sibling traversal/search tools, and it omits the default direction value.

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 the burden, and it does add one genuine behavioral fact beyond the schema: totals are returned alongside results so an empty result can be distinguished from an empty corpus. However, it omits other useful traits such as read-only confirmation, ordering, and how the limit interacts with pagination.

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 tightly written sentences that are front-loaded with the definition of scope and end with the practically relevant empty-vs-empty-corpus note. No filler; only slight compression loss from the list-like first clause.

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, and the description only partially covers the return shape (it mentions totals but not result structure). For a query tool with no annotations and an undocumented limit parameter, it is adequate but leaves ordering, result fields, and pagination behavior unaddressed.

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%: run_id is richly documented inside the schema (attribution, validation, principal ownership), while limit has no description anywhere. The description adds nothing about parameters, so it does not compensate for the undocumented limit parameter.

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 precisely defines the resource scope it returns: open questions nobody has addressed, untested hypotheses, and hypotheses tested exactly once. That is specific and lets an agent understand the concept quickly, though the retrieval verb is only implied by the name and it never names a sibling to distinguish itself from.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no reference to alternatives among the many methodist_* siblings. The intent (find gaps to work on) is inferable, but nothing tells the agent what condition should select this tool over methodist_get_current_dose, methodist_find, or methodist_hypotheses_for_question.

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?

No annotations are provided, so the description carries the burden. It discloses that the tool combines vector similarity with BM25 full-text matching, which is a meaningful behavioral trait beyond a simple search label. It does not explicitly state read-only guarantees or result ordering, but the search nature and schema descriptions cover most of the remaining 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?

Three sentences deliver purpose, capability, and routing with no redundancy. Each sentence earns its place and the key differentiator 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?

For a tool with 14 parameters and no output schema, the description provides the essential high-level orientation, while the schema fully documents the parameters. Return-payload details are covered by the detail parameter's enum rather than the description, which is acceptable given the schema's richness.

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 lists filters (content type, entities, categories, date range) already present in the schema and adds no parameter-level details beyond noting exact terms like paper IDs and author names.

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

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

The description states a specific verb and resource: 'search across scientific papers', and explains the hybrid semantic + keyword approach. It differentiates from siblings by naming search_keyword and search_semantic and positioning itself as the default for general 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?

Explicitly gives routing guidance: 'Default mode for general queries — use search_keyword for exact-term lookups or search_semantic for pure paraphrase queries.' This tells the agent when to use this tool and when to choose an 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 carries the full burden and it does disclose real mechanism: BM25 term matching, no semantic vectors, and a speed positioning ("fastest option"). However it says nothing about return shape, pagination, result limits, or the attribution requirements that the schema's run_id parameter implies, leaving notable behavioral gaps for a 13-parameter 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?

Three short sentences, front-loaded with the mechanism and the routing decision, with no padding. Slight redundancy between "optimal for exact-term lookups" and "when you know the specific term you're looking for" costs it the top mark.

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 high-complexity tool the description correctly focuses on the routing decision, which is the part the schema cannot express, and the 100%-covered schema handles the 13 parameters. No output schema exists, but the detail parameter documents return shape, so the omission of return-value prose is acceptable.

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% and the schema itself carries unusually rich parameter guidance (match-mode semantics, query caveats pointing to find_by_id, detail levels, run_id attribution rules). The description adds nothing parameter-specific beyond restating that exact terms work best, so the baseline 3 applies.

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

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

States a specific verb and mechanism ("Pure keyword (BM25) search") plus the resource it operates over, and explicitly contrasts itself with search_semantic and search. An agent can distinguish it from every sibling without opening a schema.

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

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

Gives explicit when-to-use ("when you know the specific term you're looking for") with concrete examples (paper titles, author names, method names, arXiv IDs), an explicit when-not ("Does NOT use semantic vectors"), and names the alternative tools to prefer for conceptual queries.

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 of behavioral disclosure. It discloses the retrieval mechanism (dense vector similarity), the embedding models used, and a deliberate behavioral choice — skipping BM25 fusion to avoid term-matching noise. This is substantive behavioral context beyond a generic 'semantic search' label, though it does not cover ranking behavior or empty-result semantics (the specter2 invisibility caveat lives only in the vectorModel parameter 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 with no waste: the core purpose is front-loaded, the mechanism follows, and the final sentence routes to alternatives. Every sentence earns its place, and there is no repetition of schema content 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 14-parameter tool with an exceptionally rich schema (every parameter documented, enums explained, the SPECTER2 coverage caveat detailed), the description fully covers the selection and routing job: what the tool is, how it works, when to prefer it, and which sibling to use instead. Return-value behavior is already documented via the 'detail' parameter, so the absent output schema is not a real gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds mild semantic framing for the query parameter (paraphrased ideas, 'papers arguing X') that mirrors — but does not exceed — the schema's own query description. All 14 parameters, including enums, defaults, and bounds, are already fully documented in the input 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 a precise verb+resource+mechanism: pure semantic (vector) search over the corpus using dense embeddings via Gemini or SPECTER2. It also names the siblings it is not ('search_keyword' for exact terms, 'search' for mixed), so an agent can differentiate it from both sibling search tools without opening a schema.

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

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

Provides explicit when-to-use guidance ('best for paraphrased queries, concept exploration, papers arguing X') and explicit when-not-to with named alternatives: 'For exact terms use search_keyword. For mixed queries use search.' It additionally explains the reasoning (skips BM25 fusion to avoid term-matching noise), letting the agent reason about the tradeoff rather than just memorize a rule.

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.