ScienceShot data-centre intelligence and physics reference

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

Annotations already establish read-only, idempotent, non-destructive, closed-world semantics, so the bar is lower, and the description still adds real behavioral context: Bearer-token authentication with a personal key, a free tier that returns rounded example values versus a Premium tier with low/high figures, and a metered cost of one run per answer. That billing and entitlement disclosure is exactly the kind of trait annotations cannot express. It does not describe caching, latency, or per-key rate ceilings, which keeps it from 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 dense sentences: the first front-loads what the tool returns, the second covers auth, entitlement tiers, cost accounting, and valid inputs. Every clause carries information, but the first sentence is a long comma-separated list that is heavier than it needs to be; a short lead sentence plus the field list would scan faster.

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 bears the burden of describing the response, and it does so partially: it names the figures returned and explains that free keys yield rounded example values while Premium keys return figures with low and high bounds. Auth requirements and the set of valid markets are also covered. The one residual gap is the precise shape of the response (nesting, units per field, how low/high are represented), which is left implicit.

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?

There is a single parameter at 100% schema description coverage, so the baseline would be 3. The description earns above baseline by enumerating all seventeen valid market values (Amsterdam through Zurich), which supplies an effective enumeration the schema lacks — no enum is defined, and the schema only gives 'e.g. Frankfurt, Milan'. That materially reduces invalid-input risk.

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

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

The description states a specific resource — the input figures of a colocation data-centre business case for one European market — and enumerates the concrete fields (construction cost per MW, colocation prices per kW-month, electricity price, staff, guarding, property tax, exit yield, grid wait, permitting, grid charges). That is far more specific than the title alone and lets an agent tell it apart from grid_connection_status or grid_carbon_and_price_now, which cover single dimensions rather than a bundled business case. It stops short of naming a sibling as the alternative, so it is clear but not explicitly differentiated.

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 context is implied rather than stated: the agent learns a personal ScienceShot key is required, that each answer consumes one run, and which markets are valid. There is no explicit when-to-use guidance nor any exclusion pointing to the sibling tools (data_centre_market_overview, grid_connection_status) for narrower questions. Adequate but with a clear routing 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world semantics, so the safety profile is covered. The description adds a genuine domain invariant beyond the annotations — the Gy/Sv separation — which prevents a class of incorrect calls. It does not cover edge behavior on unknown units or case sensitivity, keeping it from 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 short sentences, zero filler, with the core operation stated first and the guardrail immediately after. Nothing could be removed without losing information.

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

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

The tool is simple (3 required scalars, no output schema), and the description covers the operation and its main constraint. However, with zero enums on `from` and `to`, an agent has no way to know the accepted unit vocabulary (e.g. mGy, rad, rem, mSv) or how invalid units are handled. That gap is the main shortfall for otherwise adequate coverage.

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

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

Schema coverage is 100%, so the baseline is 3. The description does add meaning to `from`/`to` by constraining which unit pairs are legal, which matters because neither parameter has an enum. Beyond that it offers no syntax, casing, or accepted-value guidance.

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?

Uses a specific verb ('Convert') and a precise resource ('a radiation value between units of the same quantity'), so the operation and its scope are unambiguous. It does not name or differentiate from siblings, but the sibling list is entirely unrelated tool domains, so differentiation adds little here.

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 operating condition (same quantity) plus an explicit exclusion: Gy and Sv are never converted into each other, with the reason given (needs a radiation weighting factor). That is a real when-not rule. It stops short of naming a fallback tool for the cross-quantity case, which keeps it off 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/non-destructive and closed-world, so safety is covered; the description instead contributes model provenance and assumptions (PARMA 4.10 grids, JAEA, US Standard Atmosphere, vertical cut-off rigidity for the present epoch, A340 reference mass, log-linear altitude / linear Rc-W interpolation). It does not state accuracy or uncertainty, so it stops short of a 5, but the assumptions disclosed are exactly what an agent needs to judge fitness.

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 computed quantity and units before model details, and every clause is substantive. The parenthetical model stack (PARMA/US Standard Atmosphere/A340/interpolation) is dense and partially redundant with the range restatements, 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?

With no output schema, the description still names both returned rate quantities, their units (uSv/h), and the additional stay/flight effective dose, so an agent knows what comes back. The env/altitude coupling and the solar-input rule cover the non-obvious invocation risks.

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

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

Schema coverage is 71%, and the description adds meaning beyond the schema: the w_index/solar mutual exclusivity is stated only in prose, and solar enum values are anchored in time (min = December 2009, max = August 2024). Ranges restated from the schema (0-150, 0-20 km, 0-6 km) are redundant, and how `hours` maps to "effective dose of a stay or flight" is only implied.

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 named quantities (cosmic-ray ambient dose equivalent rate H*(10) and effective dose rate E, ICRP 116) in explicit units, scoped to cabin (0-20 km) or ground (0-6 km). No sibling tool in the list computes cosmic-ray/aviation dose, and the description explicitly disclaims route integration, routing that need to EXPACS.

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?

States when to use (single position, cabin or ground, given latitude/longitude and solar activity) and when not to ("Galactic cosmic rays only, one position and no route integration; for route doses use EXPACS"). It also resolves the solar-activity input choice: "Give either w_index (0-150) or solar (min ... max)".

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 and openWorld=false, so safety and scope are covered. The description adds meaningful context beyond that: results are "dated" (point-in-time), the price and carbon figures are "this hour" (freshness), and it is an aggregate rather than a single-fact lookup. It does not say what happens for an unsupported market name, nor how stale the pipeline figures may be.

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: the content inventory comes first, then usage examples, then valid values. Every clause earns its place except the long country roster, which is verbose but justified given there is no enum in 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 no output schema, the description carries the burden of describing returns, and it does so by listing the seven categories of data the caller will receive. It also supplies the full valid-market vocabulary. Remaining gap is structural: no indication of the response shape or error behavior for an unknown market.

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% for the single `market` parameter, so the baseline would be 3. The description exceeds that by enumerating the complete accepted value set — 7 metros and 24 countries — which the schema only hints at with examples and which no enum enforces. This materially reduces the risk of an unsupported market string.

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

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

Opens with a specific verb+resource+scope ("Dated overview of a European data-centre market") and then enumerates the concrete contents: project counts ≥500 kW, permitted/building split, top developers, grid connection regime, carbon intensity, power price, rule count. That is far more than a restatement of the name. It stops short of naming the sibling tools that cover single slices (grid_carbon_and_price_now, grid_connection_status, data_centre_rules), so differentiation must be inferred from the composite framing.

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

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

Provides explicit trigger phrasing ("Use for questions like 'data centres in Germany', 'Frankfurt data centre market'") which maps naturally onto the single `market` parameter. It gives no when-not-to-use rule or pointer to the narrower sibling tools, so an agent cannot learn from this text that the individual grid/rule tools exist as alternatives.

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

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

Annotations already declare this as a safe, idempotent, non-destructive read, so the safety profile needs no restatement. The description adds return-value behavior that annotations cannot convey — each rule carries a status, an applicability scope, and a next relevant date, plus upcoming deadlines — which meaningfully sets expectations for the response.

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 functional sentence is front-loaded and dense with useful detail; the trailing country list is long but is the one piece of information an agent cannot get from the schema. Slight penalty because that list dominates the text and would arguably serve better as schema enums.

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 a single fully-described parameter and no output schema, the description supplies the missing half: what a result record contains (status, applicability, next date) and that upcoming deadlines are included. Nothing an agent needs in order to call this tool correctly appears to be 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 coverage is 100% and only one parameter exists, so baseline would be 3; however the description enumerates all 29 accepted country values, which the schema does not (its only hint is 'A European country, e.g. Germany'). That enumeration closes a real risk of invalid input, though it gives no formatting guidance such as casing or name variants.

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?

Names the specific resource (national and EU rules for building and running a data centre) plus the scope ('in one European country') and the sub-topics covered (energy efficiency reporting, waste heat, permitting, grid). It is distinguishable from siblings like data_centre_market_overview or grid_connection_status 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?

Usage is only implied by the content: an agent can infer this tool answers 'what rules/deadlines apply in country X' rather than 'what is the market/grid doing'. There is no explicit when-to-use statement, no exclusions, and no routing to the sibling tools.

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

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

Annotations already establish that this is a safe, read-only, deterministic calculation. The description adds useful domain behavior beyond that: it assumes full charge collection without gain and specifies operating temperatures for Si and Ge, which materially affects interpretation of the result.

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 returned quantities, followed by assumptions and defaults. Every sentence contributes useful information with no filler.

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

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

For a five-parameter physics calculator with no output schema, the description does well by listing output quantities, stating assumptions, and giving defaults. It lacks explicit guidance on when to choose this tool over related calculations, which is the main remaining gap.

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

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

The schema covers 60% of parameters, but the description adds meaningful defaults not present in the schema: muon, 3000 MeV/c, silicon, and 300 micrometres. It does not fully explain the kinetic-vs-momentum choice, but the schema already covers that alternative.

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 detector-signal quantities returned: electron-hole pairs, collected charge, energy deposit, and Landau FWHM. Combined with the title, an agent can tell this is a silicon/germanium detector response calculator, though the verb is implicit rather than explicit and no siblings are named.

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 does not explain when to use this tool versus alternatives such as energy_loss or photon_attenuation. It gives defaults and physical assumptions, but no explicit selection guidance or exclusion conditions.

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/closed-world, so the safety profile is covered. The description adds real behavioral context beyond them: the thin-absorber assumption (results are not valid for thick targets) and the beta*gamma 0.05 truncation of the range, which tells the agent when results stop being trustworthy.

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

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

Two dense sentences, front-loaded with the model and result types, then the validity limit, then the inputs. Slightly telegraphic ('give momentum or kinetic energy and thickness') but 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 should say what comes back; it says 'estimates and a CSDA range' but gives no units or output structure for the loss estimates. Physics validity and input modes are covered, so it is adequate but leaves a real gap for a 6-parameter scientific tool.

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

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

Schema coverage is 100%, so every parameter including the momentum/kinetic either-or is already documented. The description's 'give momentum or kinetic energy and thickness' merely restates the schema without adding units, ranges, or precedence rules, 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?

Names the specific physics models (Bethe, Landau, CSDA range) and the resource (heavy charged particle energy loss), so an agent knows exactly what computation happens. It does not, however, distinguish itself from the closely related sibling synchrotron_loss or photon_attenuation, which an agent would need to choose between.

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

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

The phrase 'range is truncated at beta*gamma 0.05' implicitly states the validity domain (low-beta particles are out of scope), which is useful usage context. But there is no explicit when-to-use versus the sibling loss/attenuation tools, and no exclusions beyond the implicit truncation.

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 behavior, so the description focuses on domain-specific traits: data provenance, the distinction from H*(10), lack of build-up factor, and isotope-specific branching details. This adds substantial value beyond structured fields.

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

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

Three sentences, front-loaded with the core computation, followed by essential caveats. Every sentence is informative with 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?

Given high schema coverage and no output schema, the description covers computational basis, limitations, and isotope specifics well. It does not explicitly state the return value (e.g., units of air-kerma rate), leaving a minor gap for a computation tool.

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

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

Schema coverage is 86%, so parameters are well-documented. The description mentions optional shielding and inverse-square application, but does not add much parameter-level detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb ('Compute') and a precise resource ('point-source air-kerma rate constant') with details on data sources (NNDC, NIST, LNHB). This clearly distinguishes it from siblings like photon_attenuation or radioactive_decay, though no sibling is named explicitly.

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 what the tool does but gives no explicit guidance on when to use it versus alternatives (e.g., other radiation calculation tools). No when-not conditions or prerequisites are 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 declare readOnlyHint=true, destructiveHint=false and closed-world, so the safety profile is covered. The description adds real behavioral context the annotations lack: the fields returned, the cleanest-window and ranking behavior, and the time-sensitivity ('this hour's') that explains why an identical read is not idempotent. It does not discuss pagination or freshness lag, 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 payload (carbon, renewable share, price, window, rank) in the first sentence and defers the market enumeration to the end. The long market list is dense but earns its place since there is no enum in the schema. Slightly verbose overall, so not 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?

No output schema exists, so the description correctly carries the return-value burden by naming every returned field and the ranking/cleanest-window semantics. Combined with the covered annotations and the explicit enum-free market list, an agent has everything needed to invoke and interpret the tool.

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

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

With one optional parameter and 100% schema coverage, the baseline is 3. The description exceeds that by enumerating the 15 valid markets (Germany, United Kingdom, France, etc.), which the schema does not capture as an enum, directly resolving the main ambiguity about what values 'market' accepts.

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 concrete verb+resource: it returns this hour's grid carbon intensity (with unit gCO2/kWh), renewable share, day-ahead price, the cleanest window ahead, and market rank. The resource is clearly distinct from the siblings (data centre overview/rules, grid connection status, science search). An agent knows exactly what data this yields without opening the schema.

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

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

Gives explicit conditional behavior: with a market it returns that market's data; 'Without a market: all markets ranked cleanest first.' This tells the agent how to call it in both modes. It stops short of naming alternatives or exclusions, so it is clear context rather than full when/when-not routing.

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 and non-destructive, so safety is covered. The description adds value beyond them by describing what each result contains (measure name, scope of application, start date) and the geographic coverage, which matters because there is no output 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 scope statement is front-loaded and the trailing examples are compact and genuinely useful for routing. Slightly longer than necessary given the schema already documents the country default, but there is little waste.

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

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

For a one-parameter, read-only lookup with no output schema, the description covers coverage area, returned fields, default behavior and example intents. An agent has everything needed to invoke it correctly and interpret the result.

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 optional parameter is fully documented there, including the same leave-out default the description restates. The description adds no new format or syntax detail, 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?

Names a specific resource (new grid connections for data centres in Europe) and enumerates the exact statuses returned (paused, rationed, conditional, congested) plus the fields attached to each measure. An agent can distinguish this from grid_carbon_and_price_now purely from the description.

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?

Two concrete sample questions anchor the intended use case and the description states the no-country default ('the whole ranking'). It does not name a sibling as the alternative or state when not to use it, so it falls short of 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?

Beyond the read-only and idempotent annotations, it discloses the fixed 161-point density output and the important regime-dependent behavior: Gaussian regimes include sigma_mev and invalidate the returned Landau curve. It also states defaults, although regime selection and the curve's range and units remain unspecified.

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 compact sentences front-load the purpose and outputs, then present the key validity caveat and invocation defaults. The terminology is dense, but each clause supplies useful information with little redundancy.

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

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

The definition is sufficient to invoke the tool with or without arguments and warns about the main output-validity trap, which is especially valuable because there is no output schema. For a specialized numerical tool, it still leaves output units and structure, the density-point abscissa, and regime thresholds unclear.

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

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

With 75% schema coverage, most inputs are already documented, but the description usefully adds defaults for all four arguments: muon, 10000 MeV/c, silicon, and 300 micrometres. It does not explain the particle enum codes beyond the default or clarify valid material identifiers.

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

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

The description identifies a heavy-particle energy-loss calculation and names distinctive outputs such as MPV, Landau FWHM, finite-transfer Bethe mean, and density points. Its purpose is clear, but it does not explicitly differentiate the tool from siblings such as energy_loss or detector_signal.

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 heavy-particle scope and the warning that the Landau curve is inapplicable in Gaussian regimes provide meaningful context and an explicit limitation. However, there is no guidance on when to choose this tool over energy_loss or another sibling, or what alternative workflow to use in Gaussian regimes.

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 readOnlyHint, idempotentHint, and destructiveHint already covering safety, the description adds useful behavioral context: output units, density basis, NIST ESTAR density-effect table inclusion, and a PDG 2024 citation. It does not describe behavior for invalid or unknown material names, which is a minor gap.

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

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

The description is front-loaded with the returned property list and uses only three sentences with no obvious filler. The long first sentence is dense but appropriate given the amount of returned data it summarizes.

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

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

There is no output schema, so the description carries the burden of explaining return values, and it does so by listing the properties, units, density basis, and data sources. For a one-parameter lookup tool with strong annotations, this is sufficiently complete 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 100%, and the schema already documents the single material parameter with an example. The description repeats the name/ID instruction and adds the useful constraint of 17 available materials, but it does not enumerate or further constrain valid values.

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 resource as material properties and lists the specific quantities returned for 17 materials. However, it does not explicitly state a retrieval verb or differentiate the tool from sibling physics tools such as energy_loss or photon_attenuation.

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 instruction 'Give a material name or ID' implies how to invoke the tool, but there is no explicit guidance on when to use this lookup versus related sibling tools. Usage is therefore implied rather than directed.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the meaningful physics caveat that results are narrow-beam (no buildup factor) and sourced from NIST XCOM, but does not say what quantity is returned (μ, μ/ρ, or transmission fraction), which matters for a calculation tool.

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

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

Two short sentences, zero filler, with the core identification front-loaded and the unit reminder placed second. Nothing is wasted.

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

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

For a simple read-only calculation with fully described parameters, the definition covers inputs well. However, with no output schema, the description should say what the result represents (attenuation coefficient vs. transmitted intensity), and it does not — a real gap for a computational 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%, so all three parameters are documented in the schema itself. The description's 'thickness in mm and energy in keV' merely restates what the schema already says, adding no new semantics such as accepted material ID formats or energy range limits. Baseline 3 is appropriate.

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

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

The description names a specific physical quantity (narrow-beam photon attenuation) and the authoritative source (NIST XCOM), which clearly distinguishes it from siblings like energy_loss or material_properties. It stops short of a full verb phrase describing the computed output, but the resource and method are 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 states unit conventions for inputs but gives no guidance on when to choose this tool over energy_loss or material_properties, and no prerequisites or exclusions. An agent must infer applicability (shielding/attenuation calculations) from the tool name alone.

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?

It reveals critical behavioral traits beyond the structured data by specifying that the calculation uses 'NuDat 3 half-lives and branching.' This informs the user that the calculation is based on a specific, established scientific model, which is more valuable than merely saying 'calculates decay.'

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 tool definition is a single, highly dense sentence where every clause serves a critical purpose. There is zero fluff, making it maximally concise and effective.

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 that the input schema is complete and the calculation method is stated, the description fully equips the agent to understand exactly what the tool performs and what inputs it requires without needing external documentation.

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

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

With 100% schema description coverage, the baseline for this score is 3. The description provides functional context to the parameters (e.g., 'supply an isotope ID' instead of just 'isotope'), but does not add novel meaning beyond what the detailed schema already provides.

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

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

The description is highly specific, using the verb 'Calculate' in the context of 'parent and daughter activities.' It clearly defines the scope of the physics calculation using NuDat 3 methodology.

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 clearly dictates the necessary inputs required for the calculation (isotope ID, initial activity, and time units). While it does not explicitly compare itself to other complex physics tools, it sets a clear functional boundary for its usage.

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, idempotent, non-destructive and a closed corpus (openWorldHint=false). The description adds the genuinely non-obvious behavioral fact that results are capped at 5 pages and that each result carries title, date, link and summary, which annotations 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?

Two sentences, no filler: the corpus scope comes first and the result shape second. Every clause carries information an agent can act on.

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 search with no output schema, the description covers the corpus, the hard result cap and the return fields, so an agent can call and interpret it. It stops short of explaining ranking or how to retrieve results beyond the first five.

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 query parameter is documented in the schema with concrete examples ('PUE benchmarks', 'fibre latency London Frankfurt'). The description adds no syntax, quoting or format guidance beyond that, 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 a scoped resource (ScienceShot's trackers, reference pages, articles) and even enumerates the topical domains covered. That makes it immediately distinguishable from siblings like data_centre_market_overview or grid_connection_status, which are specific lookups rather than general search.

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: an agent can infer this is the fallback for free-text discovery when no specific sibling lookup applies, but the description never states that. There are no when-not conditions or explicit routing to the sibling tools.

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

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

Annotations already declare readOnly, idempotent, closed-world behavior, so the safety profile is covered elsewhere. The description adds real value by naming the physics basis (CODATA 2018, classical radiation formulae) and clarifying that the result is beam radiation rather than facility electrical demand, but it says nothing about output units or validity ranges for the computed quantities.

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 dense sentences: outputs first, then required inputs and the either-or constraint, then modeling assumptions and scope. No filler, and the most decision-relevant content is front-loaded.

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

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

With no output schema, the description does the work of naming the returned quantities (loss per turn, radiated power per beam, critical photon energy, optional revolution frequency), which is what an agent needs to pick this tool. It omits the units of those returned values, the one remaining gap for a physics calculator with no output schema.

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

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

Schema coverage is 83%, so the schema already documents nearly every parameter including the radius/field mutual exclusion. The description reinforces the either-or constraint and adds one genuinely new detail — that optional circumference yields revolution frequency — which is not in the schema. Otherwise it largely restates 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?

States a specific verb ('Calculate') plus the exact quantities produced: dipole synchrotron energy loss per turn, radiated power per beam, and critical photon energy, scoped to an isomagnetic ring. It separates itself from facility-level tools ('beam radiation rather than facility electrical demand') but never explicitly distinguishes itself from the sibling energy_loss.

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 invocation conditions: supply total beam energy including rest energy, beam current, and exactly one of bending radius or dipole field. It stops short of naming alternatives (e.g. energy_loss) or stating exclusions, so the agent must infer which tool wins when both could apply.

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 safety (readOnly, idempotent, non-destructive), yet the description adds real behavioural context: the SpekPy 2.5.4 engine, 12-degree anode, 2.5 mm Al inherent filtration baked into results, interpolation between stored kVp, XCOM filters and NIST SRD 126 mu_en/rho, and the scatter-free inverse-square geometry. It stops short of stating accuracy limits or failure modes, so not quite 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, front-loaded with the deliverable quantities so an agent sees the outputs first. The second sentence is dense with implementation detail (SpekPy version, interpolation scheme, SRD 126) that is partly engineering trivia, keeping 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?

No output schema exists, so the description carries the burden of naming return values, which it does completely (spectrum, mean energy, HVLs, air kerma, removed kerma fraction). It does not say how those results are structured or packaged, a minor residual gap for a pure computation 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?

With 75% schema coverage the schema already documents kVp range, mAs, distance and filter thickness. The description reinforces 'added filters' and 'inverse-square distance' but adds little syntax or format meaning beyond the schema, and never ties mAs to the fluence/air-kerma scaling explicitly.

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 ('Calculate') plus an enumerated set of concrete resources: tungsten tube spectrum, fluence-weighted mean energy, Al/Cu HVLs, air kerma and filter-removed kerma fraction. This clearly separates it from generic siblings like photon_attenuation or gamma_dose_rate, which do not generate tube spectra.

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 is only implied by the output list and the physics caveats ('Narrow beam without scatter'), so an agent can infer this is for diagnostic-kVp spectral modelling but gets no explicit when-to-use, when-not, or named alternative among siblings such as photon_attenuation.

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