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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond them: text is truncated at max_text_chars and lists are returned capped with totals, which tells an agent the payload may be lossy. Auth requirements and error behavior remain unstated.

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 plus a short routing clause, front-loading what the tool returns before the parameter and follow-up guidance. The section enumeration is long but directly useful; there is essentially 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?

An output schema exists, so return-shape exposition is not required, and the description still sketches the sections usefully. Combined with the truncation/capping note and the sibling handoff, an agent has enough to call it correctly; only permission/error context 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?

Schema description coverage is 100%, so include, package, revision and max_text_chars are fully documented in the schema itself, making 3 the baseline. The description largely restates the section list and truncation rule rather than adding new syntax or format guidance for the 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?

States a specific resource (a package's EML) and its projection into named sections (overview, people, coverage, methods, rights, project, entities), so an agent knows exactly what comes back. It does not differentiate itself from the closest sibling edi_get_package, leaving some ambiguity about which retrieval tool to pick.

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 concrete usage for the include parameter ('Choose sections with include') and an explicit next-step handoff ('call edi_list_entities for column definitions, units and codes'). It stops short of stating when to prefer this over edi_get_package or edi_search_packages.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered; the description adds useful behavioral context by disclosing the returned surface and the flexible identifier forms (package id, series, DOI, portal/PASTA URL, scope). It stops short of auth/rate-limit or resolution-failure behavior, so not a 5.

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

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

Front-loads the return contents, then accepted inputs, then the next-step routing — a logical order with no filler. It is somewhat dense and repeats schema-level input details, which keeps it from a 5.

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

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

An output schema exists, so enumerating return fields is technically redundant, but it aids selection; the description covers inputs, sibling routing, and scope. Nothing essential for correct invocation 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?

Schema description coverage is 100%, so both parameters are already documented; the description largely restates them ('series (newest unless revision is set)', 'site codes or scope names'). The 'newest unless revision is set' default interaction is mildly clarifying but duplicates the schema's own note, so 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 (get) and resource (one package revision) and enumerates exactly what the overview contains: title, publication date, creators, license, DOI, URLs, newest-revision flag, and data entities with sizes. It also implicitly distinguishes itself from siblings by pointing at edi_get_metadata and edi_list_entities.

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

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

Explicitly routes the agent: 'Next: call edi_get_metadata for the full description or edi_list_entities for columns', naming both alternatives and the condition that selects each. It also states the accepted identifier forms, so the agent knows when this tool is applicable.

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

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

Annotations already declare readOnly, idempotent, open-world, and non-destructive behavior, and the description adds useful context such as the PASTA/DataONE URLs and the optional SHA-1 checksum behavior. It could say more about pagination or authentication, but it adds meaningful behavioral detail beyond the annotations.

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

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

The description is front-loaded with the core operation and remains dense but purposeful; the final sentence routes to next tools. It is somewhat overpacked with return-field details, but nothing is clearly wasteful.

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

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

Given the output schema and annotations, the description provides enough context to call the tool correctly and know what to do next. It covers the package-revision scope, returned entity details, checksum option, URLs, and follow-up tools.

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 input schema already documents all seven parameters thoroughly. The description does not add substantive parameter-level semantics beyond what the schema provides, which is appropriate but not exceptional.

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 that this tool lists every data entity in one package revision and enumerates the returned fields, making the resource and scope specific. It does not explicitly name sibling tools such as edi_get_package or edi_get_metadata, so sibling differentiation is implied rather than stated.

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

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

It gives clear next-step guidance: call edi_preview_entity or edi_download_entities with an entityId. It does not explicitly say when to choose this over sibling package/metadata tools, but the intended usage context 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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds non-obvious domain behavior: results are ascending, paging is offset/limit, and identifiers are numeric with package = scope.identifier.revision. No mention of rate limits or auth, hence not a 5.

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 core action and scope semantics before the pagination note and the next-step pointer. No filler and nothing buried.

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

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

An output schema exists, so return shape need not be explained, and all parameters plus the safety annotations are fully specified. Domain specifics an agent needs (scope forms, identifier numbering, paging) are all present, leaving nothing material missing for correct invocation.

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

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

Schema coverage is 100%, so all three parameters are documented in the schema with bounds and defaults; baseline 3 applies. The description restates the scope forms and paging model but adds no syntax or edge-case detail 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?

States a specific verb and resource ("List the package identifiers in one scope") plus ordering and pagination behavior, and clarifies the scope forms with concrete examples. It also distinguishes itself from edi_list_revisions by pointing at the next call, so an agent can tell the two apart 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 a clear follow-up path ("Next: call edi_list_revisions(package='scope.identifier')") and directs scope resolution to edi_list_scopes via the schema note. It never says when to prefer this over edi_search_packages, which is the main sibling ambiguity left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), but the description adds genuinely useful context beyond them: anonymous calls work yet DataONE 'can lag new revisions' without an API key, and results are returned ascending. That staleness/auth caveat is the kind of trait structured fields cannot express.

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

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

Front-loads what the tool returns and its ordering, then input forms, then the caveat, then the next step. Dense but every clause carries information; the accepted-input enumeration is the only slightly redundant part.

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

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

With an output schema present, return values need no explanation, and the description covers input formats, the anonymous-access caveat, and the follow-up call. It lacks any note on error behavior for an unknown/invalid identifier, which is the one remaining gap for a lookup 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 description coverage is 100% and the single parameter's accepted formats (series, revision, DOI, portal/PASTA URL, site code) are already documented in the schema; the description largely restates them. No additional syntax or normalization rules are added, 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 resource ('List every revision of one data package'), names the identifier form (scope.identifier), and specifies ordering (ascending, with newest and oldest). An agent can distinguish this from edi_get_package or edi_list_identifiers 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 a concrete follow-up chain ('Next: call edi_get_package(package=newestPackageId)') and enumerates accepted input forms, which tells the agent when this tool is the right entry point. It does not explicitly say when to prefer a sibling such as edi_list_identifiers, so it stops short of full when-not guidance.

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

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

Annotations already cover readOnly/idempotent/openWorld/non-destructive, and the description adds meaningful context beyond them: results come live from PASTA with an API key and from a dated snapshot without one, with a mirror at edi://reference/scopes. It stops short of describing how large the list is or how stale the snapshot is.

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 tight sentences: purpose and payload first, then the API-key/snapshot caveat, then the next-step routing. Every sentence carries information an agent would otherwise have to infer.

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

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

With an output schema present, the return values need no further explanation, yet the description still summarizes them. Auth-dependent behavior and downstream usage are both covered, leaving nothing essential missing for a correctly-invoked call.

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 'kind' parameter is fully documented in the schema with its enum meanings, so the schema does the heavy lifting (100% coverage). The description adds no further explanation of the kind filter, though it does clarify that scope names/site codes serve as identifiers across tools.

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 (list the repository's scopes) and enumerates the returned fields: name, kind, LTER site code, location and package counts on PASTA and DataONE. The example scope IDs (knb-lter-hbr, edi) make it immediately distinguishable from the sibling list/get 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?

Explicitly frames this as a discovery step and routes onward: 'Next: call edi_search_packages(scope=...) or edi_list_identifiers(scope=...).' It also warns that 'Scope arguments elsewhere also accept these site codes and names,' which tells the agent why to call this before 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?

Annotations already declare readOnly/idempotent/non-destructive/open-world, and the description adds substantial context beyond them: it never reveals the key, it discloses backend routing logic based on key presence, states which tools require a key, and explains that check_api triggers one small (cost-bearing) request to the backend. This is exactly the extra behavioral detail annotations cannot carry.

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 capability list is front-loaded and dense with no filler, and the actionable next step lands last. However, the opening sentence is a long run-on enumerating five separate facts, which slightly hurts scannability.

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

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

Although an output schema exists, the description still summarizes the report contents (version, protocol, key availability, backend, key-requiring tools, downloads), and it covers the one optional parameter's side effect. An agent has everything needed to decide whether and how to call this 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 description coverage is 100% and the single parameter is fully documented in the schema, including the token exchange and DataONE query mechanics. The description restates check_api mostly in terms of intent ('confirm the key and connectivity'), adding only marginal meaning beyond the schema, so 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+resource ('Liveness and capability report') and enumerates exactly what it reports: server version/protocol, EDI API key availability, backend routing (pasta vs dataone), which tools need a key, and download status. This is clearly distinguishable from the data-fetching siblings like edi_get_package or edi_search_packages.

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 concrete usage context (use check_api=true to verify the key and connectivity) and an explicit next step: 'call edi_search_packages to find data packages.' It does not name a competing tool it should be chosen over, but for a diagnostic tool the routing guidance is clear. Lacks explicit when-not-to-use guidance, so not a 5.

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

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

Annotations already declare readOnly/idempotent/openWorld, so the bar is lower, and the description still adds real behavior: only the newest revision of each package is returned, and generated bulk scopes (~36k records) are excluded unless include_bulk=true. It does not cover pagination/result-count limits, but the dedup and exclusion semantics are genuinely useful.

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 what is searchable, then return shape, then the bulk caveat, then the next-step call. It is dense but well ordered; the return-field enumeration slightly duplicates the output schema but costs little.

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 10 parameters, full schema coverage, an output schema, and annotations present, the description supplies everything else an agent needs: bulk exclusion, newest-revision dedup, and explicit follow-up tools.

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 per-parameter descriptions already carry the semantics (bbox ordering, sort enum nuances, start/end_year overlap logic). The description's parameter list is summary-level restatement rather than added meaning, 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 description names a specific verb (Search) and resource (EDI/LTER data packages) and immediately enumerates the facets it searches over, so it is unmistakably distinct from the edi_get_* and edi_list_* 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?

It gives clear context (filter by scope, author, temporal overlap, bbox; sort; paginate) and routes the agent forward with 'Next: call edi_get_package or edi_get_metadata with a packageId', plus points to edi_list_scopes for scope resolution. It lacks an explicit when-not-to-use statement, but the alternative routing is well covered.

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