SuperhotGeo

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 two useful traits: answers are grounded with cited web sources, and a SuperhotGeo API key is required. It says nothing about rate limits, cost, latency, answer length, or what happens on an out-of-domain or key-less call.

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 dense paragraph that front-loads the verb and domain, then the return format, then the auth prerequisite. Every clause earns its place; nothing is repeated from the schema.

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 one-parameter question-answering tool with no output schema, the description covers what it does, what comes back (grounded answer with citations), and the API-key requirement. Only operational details like failure modes and limits are absent, which is a minor gap at this complexity.

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

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

Schema coverage is 100% and the single parameter is fully documented, so the baseline applies. The description does implicitly constrain the question to the geothermal domain, which is meaningful, but it adds no format, length, or phrasing guidance beyond the schema's maxLength.

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?

Specific verb ("Ask") plus a named resource ("SuperhotGeo Assistant") and an enumerated domain scope covering science, technology, projects, economics, policy, companies, and the platform itself. The web-grounded answer with cited sources also distinguishes it from data-lookup siblings like search_wells or search_library.

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 domain scope plus "returns a grounded answer with cited web sources" gives clear context for when this is the right call versus the search-oriented siblings. However, no sibling is named and there are no explicit exclusions (e.g., "do not use for well-level data, use search_wells"), leaving the routing 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds what is returned (full text, canonical URL, source), but says nothing about behavior on a stale/unknown id, truncation, or size limits.

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, front-loaded with the action and its output, with zero hedging or repetition. Every clause carries information the agent needs.

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 usefully names the return payload (full text, canonical URL, source) and the origin of the id. For a one-parameter read tool that is nearly enough; only error and truncation behavior remain 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 100% and the single `id` parameter is fully documented in the schema, including the "<resource>:<recordId>" format. The description only restates that the id originates from `search`, adding no syntax or format detail beyond the structured field, 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 (fetch) and resource (full text of one record) and ties the input to `search` output, so it is distinguishable from the search tools. It does not, however, differentiate itself from sibling `get_resource`, which an agent might reasonably confuse with fetching a record.

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?

Establishes a clear workflow precondition: the id must come from a prior `search` call, which tells the agent when this tool is appropriate. It stops short of stating when NOT to use it or naming alternatives such as `get_resource` or `search_library`.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds only that exactly one record is returned; it says nothing about not-found behavior, permissions, or whether ids are global or per-collection.

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 with no padding or redundancy. It is efficient, though it is so terse that it sacrifices useful detail rather than earning brevity through completeness.

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 full schema coverage and annotation-declared safety, the description is minimally sufficient. It omits what the returned record contains and what happens when an id does not exist in the given collection, which would matter for error handling.

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 resource enum is fully enumerated in the schema, so the baseline is 3. The description restates 'by resource and id' without adding format, case sensitivity, or id-acquisition guidance beyond the structured fields.

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 gives a specific verb (fetch) and resource (a single SuperhotGeo record) and implicitly contrasts with the listing sibling by saying 'a single' record. It does not explicitly name list_resource or search, so an agent must infer the boundary rather than being told it.

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 states the retrieval is keyed by resource and id, but never says when to pick this over list_resource, search, or fetch, nor any prerequisite such as needing a known id. Usage is only inferable from the phrase 'a single record'.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral detail — trending is recomputed every 6h from recent saves/views plus recency, and trending rows carry rank/type/refId/label — but says nothing about ordering, page sizes, or total counts for other collections. With annotations carrying the safety load, this is a solid mid-range contribution.

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 is clean and front-loaded, but everything after it is one 15-clause run-on sentence that is hard to scan and would be far clearer as a list. It is dense rather than padded, yet the exhaustive enumeration still omits two enum values, so the length is not fully earning 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 exists, and the description only sketches return shape for the trending collection; for the other fourteen it says nothing about row fields, ordering, or pagination/total counts, and it never mentions the q or limit parameters. Combined with the undescribed library/jobs enum values, an agent can pick a collection but not predict what comes back.

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 the baseline is 3, but the description goes further by explaining what each enum value actually contains (e.g. artifacts include versions, licenses, provenance, reproducibility status; field_data is the vetted measured well dataset) — real semantic value beyond "Which collection to list." However the enum has 16 values and "library" and "jobs" are never described, leaving two options unexplained.

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 and resource ("List records from a SuperhotGeo public collection") and enumerates what each collection holds, so the agent knows exactly what the tool retrieves. It never contrasts itself with the sibling tools it clearly overlaps with (search, search_library, get_resource, search_wells), leaving disambiguation to the agent.

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?

Usage is only implied by the verb "list" plus the per-collection descriptions; there is no statement of when to choose this over search, search_library, or get_resource. No prerequisites, exclusions, or alternative routing are given, so the agent must infer the list-vs-search split.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: results are ids intended for `fetch`, and the corpus is a curated closed set rather than the open web. It says nothing about result limits, ranking, or empty-result behavior, so with annotations carrying safety it lands at baseline-plus.

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?

Scope is front-loaded in the first clause and the routing rule follows immediately; the long topical enumeration earns its length by delimiting the domain. Only the domain list is dense enough to skim past, and nothing is redundant with the schema.

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 one required parameter and no output schema, the description covers the two things an agent needs: what corpus is searched and what comes back (ids for `fetch`). No output schema exists, so the return-value handoff note is doing necessary work. Minor remaining gap is absence of guidance on what to do when results are empty or ambiguous.

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% and the single `query` property already documents itself with worked examples ("casing failure above 400 C", "magma Krafla"). The description adds no syntax, phrasing, or length guidance beyond the schema, 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 the verb (search) and resource precisely, then enumerates the concrete corpora covered: the Superhot Well Registry, projects, field lessons, RockLab models/datasets, open problems, and the research library. That is far more specific than the generic name 'search'. It stops short of distinguishing itself from the sibling search_wells and search_library, so an agent must still 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?

"Use it first for any question about..." is an explicit default-entry routing rule, followed by a concrete topical list (superhot rock, supercritical >374 C, EGS, well failures, projects, firm power for AI). It also names the downstream tool via "Returns ids to pass to `fetch`". It does not state when to prefer the narrower sibling searchers instead.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds only a small amount of context via "continuously curated," implying freshness, but does not describe result behavior, ranking, or rate limits.

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 wasted words. It identifies the resource and its scope immediately.

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 search tool with complete schema coverage and safety annotations, the description is largely sufficient. It could say more about result ordering or ranking, but no output schema exists and the core purpose is clear.

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 schema already documents the query and limit parameters in detail. The description adds no parameter-specific meaning beyond what the schema provides, making the baseline score of 3 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 uses a specific verb ("Search") and resource ("library of superhot geothermal news, studies, journals, and resources"), making the tool's domain clear. It does not explicitly distinguish itself from siblings like search, search_wells, or ask_superhot, 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?

It states the content being searched but gives no guidance on when to use this tool versus the sibling search, search_wells, or ask_superhot tools. There are no exclusions, prerequisites, or alternative conditions mentioned.

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

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

Annotations already establish readOnly, non-destructive, and closed-world behavior, so the description's job is to add context — which it does by listing the data returned per well (max temperature, lithology, failure modes, root cause, lessons, induced seismicity, sources). It does not mention result limits or ranking behavior, which keeps it short of 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?

Two sentences with the searchable corpus front-loaded and the use cases appended. The parenthetical well list is dense but earns its place by signaling coverage; otherwise there is no wasted 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?

With no output schema, the description compensates by enumerating the returned fields per well, which is exactly what an agent needs to judge relevance. A note on result volume or ranking would have made 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 both parameters are well documented in the schema, including the 374 °C supercritical convention. The description adds no parameter-level detail beyond what the schema already provides, so the baseline of 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 and resource (search documented superhot/high-temperature geothermal wells) and enumerates concrete example wells and the attributes indexed, so the agent knows exactly what corpus is being queried. It does not explicitly contrast itself with siblings like ask_superhot or search_library, so differentiation is left partly to inference.

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?

"Use it for drilling, completion, materials, site-comparison, or risk questions" gives clear positive usage contexts. However, it offers no exclusions or guidance on when a sibling such as ask_superhot would be the better choice.

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