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

With no annotations, the description carries the full burden. It discloses that output is a list of key/value pairs and that dates narrow the period, with a default from journal inception. However, it does not state read-only nature, required authentication, or any side effects, leaving some behavioral 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?

Two concise sentences; the first states purpose and output format, the second covers date parameters. Front-loaded and free of fluff, 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?

The description provides the essential action and date semantics, but lacks detail on the return structure (keys present), the meaning of journal, and how this differs from publication_stats. With no output schema and no annotations, more completeness would help an agent decide correctly.

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

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

Schema description coverage is 0%, so the description must explain all parameters. It explains date_from/date_to format and effect, but leaves the 'journal' parameter undefined (ID? name? optional?), and does not clarify how it is used in filtering. Incomplete compensation for the missing schema descriptions.

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

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

Description clearly states it aggregates editorial statistics for a journal and lists examples (submission count, decisions, time to first decision) plus output format as key/value pairs. It is specific about the resource and action, but does not differentiate from sibling publication_stats, so it misses the sibling distinction.

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 publication_stats or other siblings. It explains date behavior but gives no context on selecting this tool over alternatives, no exclusions, and no prerequisites.

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 behavioral burden. It signals a read-only fetch and explicitly documents the `issue: None` edge case when no current issue is set, which is valuable operational information 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?

Two concise sentences with no filler. The action and scope are front-loaded, and the edge-case return value earns its place as a separate sentence.

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 tool, purpose and the None edge case are covered, but the optional `journal` parameter is left undocumented. Because there is no output schema, a bit more detail about expected output or parameter semantics 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 single parameter `journal` has no explanation in the description, and schema description coverage is 0%. The title 'Journal' and default null provide only minimal clues; the description does not clarify whether an ID or name is expected, or what null means behaviorally.

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

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

The description uses a specific verb ('Fetch') and resource ('the journal's current issue'), and qualifies it as 'the one featured on the home page.' This clearly distinguishes it from sibling tools like get_issue or list_issues without needing to inspect their 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 home-page qualifier gives useful context for when the tool applies, but the description never names alternatives or states when to prefer get_issue/list_issues instead. Usage is implied rather than explicitly guided.

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 word 'Fetch' clearly conveys a read-only operation, which is helpful in the absence of any annotations. However, the description does not disclose behaviors like not-found handling, the effect of the optional journal parameter, or what the returned issue contains.

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

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

The description is a single, front-loaded sentence with no filler or repetition. It is appropriately concise, though it prioritizes brevity over some useful context.

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 single-fetch tool, the description plus schema is minimally viable: an agent can infer that issue is required and that an optional journal may disambiguate. Still, with no output schema and no explanation of the optional parameter or return value, there are clear gaps in completeness.

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

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

Schema description coverage is 0%, and the description only maps the issue integer to 'its ID' without explaining the optional journal parameter. The description adds minimal meaning beyond the schema's bare field names and does not compensate for the missing parameter 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 uses a specific verb ('Fetch') and resource ('one issue of a journal') with an ID-based retrieval qualifier, making the core purpose clear. It is distinguishable from siblings like list_issues or get_current_issue by the singular 'one issue' framing, though it does not explicitly name alternatives.

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 the tool is for retrieving a single issue when its ID is known, but it provides no explicit guidance on when to prefer this over list_issues or get_current_issue. There are no stated exclusions or alternative names, so usage context is only inferred.

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 makes the read-only fetch behavior clear and discloses the meaningful return additions (abstract, DOI, galleys with public links). It doesn't mention authentication or error behavior, but nothing suggests 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?

The first sentence states the operation and scope; each following sentence adds needed context without filler. Compact and 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?

Provides the retrieval path from get_submissionainer, the meaning of publication, and the distinguishing return fields. Left uncovered: the optional journal parameter, and explicit notes on permissions or failure/empty states.

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 explains the publication parameter well, including how to obtain it from get_submission. It also implies what submission refers to, but it never explains the optional journal parameter, and with 0% schema coverage, that remains a gap.

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

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

The description opens with a precise action and object: fetch one version of a submission. It explicitly defines 'publication' as a version and contrasts this endpoint's full-detail return with the trimmed list, making its purpose unambiguous.

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

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

It explains the correct call flow (find the publication ID via get_submission) and what additional data this endpoint provides. It does not explicitly name a “don’t use when” scenario, but provides clear context for when this endpoint is appropriate.

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 present, the description carries the full burden for behavior. It conveys a read-only fetch action, and the phrase 'trimmed list' warns the agent that the result deliberately excludes full version content. It does not mention permissions or rate limits, but for this simple read operation the behavior is reasonably 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?

Three sentences deliver the purpose, the return limitation, and routing to related tools with no fluff. The important need-to-know details are front-loaded, and 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?

Given the lack of an output schema and annotations, the description does useful work by outlining the rough return shape and pointing to the siblings for the omitted content. However, it still leaves the optional `journal` parameter unexplained and does not describe what fields or attributes are included beyond 'details', so an agent could still need more information.

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

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

Schema description coverage is 0%, so the description must compensate. It only explains the main required parameter as an 'ID'; the optional `journal` parameter is never mentioned or given a role. With no parameter descriptions in the schema and only titles available, this leaves an agent guessing about correct invocation.

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 an explicit verb ('Fetch') and resource ('submission (article)') by its ID, and it distinguishes itself from the related `get_publication` and `get_submission_reviews` tools by clarifying that it returns only a trimmed publications list. This is immediately understandable and not a restatement of the tool name.

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

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

The description implies clear selection criteria: use this tool for submission-level details and a trimmed list of versions, turn to `get_publication` for full version content, and to `get_submission_reviews` for review rounds. It lacks an explicit conditional such as 'use this only when you need...', but the sibling routing is still clear.

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 the return structure (review_rounds and review_assignments) and what each contains, which is helpful. However, it does not mention whether this is a read-only operation, any required permissions, or what happens if the submission has no reviews. The description adds some behavioral context 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 two sentences, front-loaded with the main purpose, and the return structure is clearly listed. Every sentence earns its place with no fluff or repetition.

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

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

For a read-style fetch tool with two parameters and no output schema, the description covers the core purpose and return fields. However, it lacks guidance on the optional journal parameter, any prerequisites (e.g., submission ID format), and edge cases like missing reviews. It is adequate but not fully complete for an agent to invoke without additional inference.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the 'submission' parameter implicitly by stating the tool fetches data 'for a submission', but it does not explain the 'journal' parameter at all. The description adds meaning for the primary parameter but leaves the optional journal parameter undocumented, which is a gap given zero schema coverage.

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

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

The description clearly states the tool fetches review rounds and reviewer assignments for a submission, using specific nouns ('review_rounds', 'review_assignments') and a clear resource ('a submission'). It distinguishes itself from sibling tools like get_submission and list_reviewers by focusing on the review 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?

The description implies usage: call this when you need review rounds or reviewer assignments for a specific submission. It does not explicitly state when not to use it or name alternatives, but the context of sibling tools (e.g., get_submission for general submission data, list_reviewers for reviewer lists) makes the intended use reasonably clear.

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 does not state whether the operation is read-only, how results are ordered, whether pagination applies, or what 'registered' versus 'unregistered' means. The status values are helpful but not enough to make the tool's behavior 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 brief and front-loaded, with the main purpose in the first sentence and the status values in a compact code block. Every part serves a purpose, though the status list could have been integrated more naturally.

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 no output schema and no annotations, the description should explain more about return values, filtering behavior, and parameter usage. It only covers the status filter, leaving limit and journal semantics ambiguous. The description is not complete enough for an agent to invoke the tool confidently in varied scenarios.

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

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

Schema description coverage is 0%, so the description must compensate for all three parameters. It adds meaning only for 'status' by listing possible values, while 'journal' and 'limit' are left entirely unexplained. This is partial compensation but not sufficient for the parameter set.

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 a specific verb and resource: 'Find the DOIs registered for a journal.' This distinguishes it from sibling tools like list_journals or get_submission, which target different resources. However, the word 'registered' is slightly inconsistent with the status list that includes 'unregistered,' so the core purpose is clear but not perfectly precise.

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. It does not mention any exclusions, prerequisites, comparison to sibling tools, or typical use case context. The status list offers some input guidance but not usage direction.

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

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

With no annotations, the description carries the full burden. It discloses a notable behavioral trait (OJS decides sort direction and cannot be reversed) and the effect of omitting published_only. However, it does not mention whether the operation is read-only, requires authentication, or any side effects. This is partial disclosure but adds value 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 concise and well-structured: a single purpose statement followed by two lines of parameter explanations with clear formatting. Every sentence adds value, and the most important information is front-loaded. No redundancy or fluff.

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

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

For a tool with five parameters and no output schema or annotations, the description is incomplete. It does not explain limit, phrase, or journal parameters, nor does it hint at the return structure or pagination. An agent would lack critical details needed to call this tool correctly, such as what phrase filters on or whether journal is required.

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

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

Schema coverage is 0%, so the description must compensate. It explains published_only and sort_by in detail, which are the most complex parameters. However, it leaves limit, phrase, and journal unexplained. This provides meaning for some parameters but not all, offering moderate compensation for the lack of schema descriptions.

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

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

The description clearly states the verb and resource: 'Find a journal's issues.' This is specific and distinguishes it from sibling tools like get_issue (single issue) and get_current_issue (current issue). The filtering and sorting options further clarify the scope of the operation.

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

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

The description explains the meaning of key parameters (published_only, sort_by) but does not explicitly guide when to use this tool over alternatives like get_issue or get_current_issue. There is no mention of exclusions or explicit conditions for choosing this tool, leaving the agent to infer from the name and purpose.

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 given, so the description carries the full burden. It communicates a read-only intent with 'List', gives the output shape, and defines the value of 'path' to other tools. However, it says nothing about empty results, pagination, or errors, and the 'visible to current credentials' phrase is still generic. This is adequate, but not especially 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 exactly two sentences. It front-loads the action and scope, then gives a concise output contract, and a useful pointer to sibling tools. There is no fluff or repetition.

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 zero-parameter, simple list operation, the description is complete. It explains the output and the direct use of 'path' in related tools, and because there is no output schema these details are essential. Nothing needed for the agent to call it successfully is missing.

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

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

The tool has zero parameters, so the baseline for this dimension is 4. The description adds relevant cross-information by telling the agent that the returned 'path' should be used as the 'journal' param elsewhere, which is useful and denies any additional semantics.

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

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

The description states a specific verb 'List' and a clear resource, 'journals', and scopes it with 'visible to the current credentials'. This differentiates it from sibling tools such as list_issues or list_sections, and it also explains that the returned 'path' is meant for other journal-based tools, removing all ambiguity about what the tool returns.

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

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

It implicitly tells the agent when to use this tool by explaining that the returned 'path' is the value to pass as the 'journal' parameter in the other tools. This is clear context for the common workflow, though it does not explicitly name or exclude 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 are present, so the description carries full burden. It discloses that the tool returns counts, averages, and ratings, which gives some behavioral context. However, it does not mention whether the operation is read-only, any authentication requirements, rate limits, or potential side effects, leaving room for improvement.

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, with two sentences that communicate the core purpose and a key parameter. The structure is somewhat mixed, as return information is embedded alongside parameter documentation, but it is not verbose and front-loads the main function.

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 and annotations, the description is incomplete. It omits details on how to specify the journal (ID vs. name), the behavior of `phrase` and `limit`, and the full structure of the response. The statement 'Find a journal's reviewers' implies a required journal, but the schema makes it optional, creating potential confusion.

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

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

Schema coverage is 0%, so the description must compensate. It explains the `status` parameter with values and defaults, which is helpful. But it provides no meaning for `limit`, `phrase`, or `journal`. While `journal` is implied by the tool's purpose, `phrase` and `limit` are left unexplained, leaving a significant semantic gap for three of four parameters.

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 ('Find'), a clear resource ('a journal's reviewers'), and what is returned (review statistics). It distinguishes the tool from siblings like list_journals and get_submission_reviews by focusing on reviewers of a journal, so an agent can infer the correct usage without ambiguity.

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 is provided. There is no mention of when to prefer this over get_submission_reviews or search_users, nor any explicit conditions or exclusions. The description only mentions the `status` parameter, which is not usage guidance.

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

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

With no annotations, the description carries the burden of explaining behavior. It does clarify the active_only filtering behavior and the implication that omitting it returns all sections. But it never states that the call is read-only, what the response shape is, or how failures/pagination behave, leaving notable gaps.

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

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

The description is compact and front-loaded: the core purpose appears in the first sentence, followed by a targeted behavioral note on active_only. There is no filler or redundant restatement of the tool name.

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 four parameters, no annotations, and no output schema, the description must explain the entire calling contract; it covers only active_only. Missing are the meaning of journal, phrase, and limit, plus any sense of the response shape. An agent could guess the intent but not confidently construct a correct request.

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 absent, and the description only explains active_one parameter: active_only. The journal, phrase, and limit parameters are not elaborated at all, forcing the agent to guess whether journal expects an ID, object, or name, and what phrase filters against.

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 action ('Find') and the resource ('a journal's sections'), with concrete examples ('Articles', 'Reviews'). It does not explicitly name sibling tools or contrast with them, but the resource is specific enough that an agent can distinguish it from list_issues or get_publication.

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

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

It offers a mild usage hint via the active_only line, explaining that the default returns all sections while true excludes disabled ones. However, it provides no guidance on when to choose this tool over alternatives, no prerequisites, and no indication of required parameters beyond the example.

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 returns files across all stages and that each file includes a human-readable stage name, which is useful. However, it does not disclose pagination behavior, whether the list is ordered, or whether any files are excluded by default.

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 short sentences, front-loads the main purpose, and the second sentence adds a valuable detail about the output. 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?

For a simple list tool with 3 parameters and no output schema, the description is mostly adequate. It explains the key output nuance (file_stage_name) but omits any mention of pagination, ordering, or the meaning of the journal parameter, which an agent might need for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the meaning of the output's stage field but does not explain the parameters (submission, journal, limit) beyond what the schema already provides. The description adds no parameter-level semantics.

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

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

The description states a specific verb ('Fetch the list of files') and a clear resource ('attached to a submission'), and adds the useful scope 'all stages'. It does not explicitly differentiate from siblings, but the resource is distinct enough among the listed 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?

The description implies when to use it (when you need files attached to a submission) but does not state when not to use it or name alternatives. Among siblings, none obviously overlap, so the lack of explicit exclusions is a minor 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?

No annotations are provided, so the description carries the burden. It discloses read-only behavior without OJS_ALLOW_WRITES, and notes that it does not enforce field lists from edit_publication_metadata. It also gives the path convention. It does not describe return format or error handling, but for a generic API caller that is likely acceptable.

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 and front-loaded with the main purpose. The write-safeguard paragraph adds important behavioral context. A few lines, no fluff.

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

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

For a generic endpoint caller, the description covers path, journal, write restrictions, and the endpoints resource. It lacks return format, but that varies by endpoint. It is reasonably 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 has 0% description coverage, so the description must compensate. It explains `path` (relative to api/v1, with example) and `journal` (index for site-level). It doesn't explain `method`, `body`, or `params` explicitly, though method is implied by the read/write discussion. Partial 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?

States a clear verb 'call' and a resource 'any OJS REST API endpoint' and explicitly says 'outside the ready-made tools,' distinguishing it from sibling tools. The purpose is 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?

Explicitly states when to use it: 'outside the ready-made tools' and points to the `ojs://endpoints` resource for available endpoints. Also clarifies journal='index' for site-level. Does not list specific sibling alternatives but the condition is clear.

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 of behavioral disclosure. It explains the return shape conceptually (ranking vs. sum of views over time) and date range handling, but it doesn't disclose potential pitfalls like default date behavior or whether the ranking is sorted ascending/descending. It adds some context beyond the schema, but lacks depth.

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

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

The description is compact and front-loaded with the main purpose. It uses bullet-like structure with explicit parameter mentions. A slight improvement could be to break out the timeline modes into separate lines for easier parsing, but the current format is efficient and not wordy.

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 moderate complexity (6 parameters, all optional) and no output schema, the description covers the core functionality but misses details like default date range behavior, ordering of the ranking, and how journal filtering interacts with timeline mode. It's adequate for a basic call, but an agent might need to introspect results to confirm semantics.

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

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

Schema description coverage is 0%, but the description explains the key parameters: timeline, interval, and date_from/date_to. It doesn't clarify 'limit' or 'journal' semantics beyond their names, but the tool is simple enough that names are somewhat self-explanatory. The description partially compensates for the coverage gap, but not fully for all six parameters.

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 provides 'publication view statistics' and distinguishes between two modes: a ranking (timeline=False) and a time series (timeline=True). This is specific and actionable, and it does not merely restate the tool name. The distinction helps the agent understand the core functionality immediately.

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

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

The description explains the two modes of operation and how the 'timeline' parameter controls them, and it specifies the 'interval' option for day or month. However, it does not explicitly state when to use this tool versus alternatives like editorial_stats, though the purpose is clear enough to infer. It could benefit from mentioning that this is for publications, not submissions or issues.

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

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

The description discloses a non-obvious behavior: date filters only apply to already-fetched pages flagged by a response field. However, with no annotations, it doesn't explain pagination behavior, return shape, or side effects/read-only semantics, leaving important behavioral gaps.

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

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

The description is compact and front-loads the core purpose, then lists parameter semantics in a scannable way. It packs a lot of value into a short space with no filler, though the formatting mixes inline and list-style hints slightly.

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 should explain return shape, pagination behavior, and exclusions such as limit, phrase, journal, and submitted_to. The date-filter caveat is valuable, but major functional gaps remain.

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 provides only names/types, so the description adds real meaning by enumerating allowed values for status, stage, sort_by, and date format. But several parameters (phrase, journal, submitted_to, limit) are left unexplained, so the coverage is only partial.

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

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

The description opens with a clear action and resource: 'Find submissions (articles) in a journal.' The parameter list reinforces the purpose by enumerating concrete filters. It doesn't explicitly contrast with sibling tools, but the core purpose is 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?

There is no guidance on when to use this tool versus alternatives like getting a single submission or its reviews. The only cross-tool hint is a reference to list_sections for valid section IDs, which is helpful but not enough to direct an agent to the right tool.

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

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

No annotations are provided, so the description carries the full burden. 'Find' implies read-only behavior, but the description does not disclose pagination behavior, search matching semantics, whether journal is required or inherited from context, or what the response contains. Some parameter values are listed, but that is semantic rather than 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 compact and front-loaded: the main purpose appears in the first sentence, and the parameter value lists are concise and scannable. There is no redundant filler.

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

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

With no annotations, no output schema, and five parameters, the description leaves important gaps: it is unclear whether journal is required or defaults to current context, what the response shape is, and how limit/pagination behaves. The ambiguity around a journal-scoped search with an optional journal parameter makes this incomplete for reliable invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It does provide useful allowed values for status and role, and the first sentence suggests phrase searches name/email. However, the limit and journal parameters are not explicitly explained beyond their names, leaving partial rather than complete compensation for the missing schema 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 states a clear verb ('Find'), a specific resource ('a journal's users'), and the filter dimensions (name/email, status, role). It does not explicitly differentiate the tool from siblings like list_reviewers, but the search/filter framing makes its purpose reasonably distinct.

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 is given about when to use search_users versus alternatives such as list_reviewers or list_journals. The description implies general search usage but provides no exclusions, prerequisites, or context for choosing this tool over a sibling.

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, this description carries the disclosure burden. It explains that API tokens only confirm auth works and identity is None, while login/password return full user data such as id, username, fullName, roles, and role_names. It does not mention failure behavior or response shape, so it is not perfect.

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 and front-loads the main purpose in its first sentence. The following auth-mode distinction is dense and useful, but the layout could be slightly smoother. Overall, 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?

For a simple tool with no output schema, the description usefully explains the identity behavior for both authentication types. However, it says nothing about how the optional journal parameter affects results, and it does not explain what the response looks like when auth fails. This makes it adequate but not 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 describes a single optional 'journal' parameter but has 0% schema description coverage, and the description never mentions this parameter. The description does not explain what journal does, whether it must be set, or what null means. This leaves the only parameter undocumented.

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

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

The description explicitly states that the tool checks whether the current credentials work and who you are, using a specific verb and resource. It foresees the difference between API token and login credentials, distinguishing its behavior clearly. No sibling tool shares this 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 text implies the tool should be used for credential validation, but it does not provide explicit when-to-use guidance, prerequisites, exclusions, or comparisons with alternative tools. It mentions auth-mode differences but not when to prefer this tool over search_users or other siblings.

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