Warmth Engine Observatory

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: tier-dependent content (free tier returns met status and headline per dimension; full tier adds constraint, qualification, and sources), the provenance and tier-independence of energy_context, and the crucial 'Descriptive — recorded status, never inference' framing. This is behavior an agent could not infer from 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?

Front-loaded with the retrieval action and its payload, then routing, then tier behavior — a sensible order. However, the energy_context clause is wordy and restates the same idea several times ('external reference data outside the WEO analytical stack, national totals, dated observations reported as published, accompanying the profiles but forming no part of them'), which could be tightened without losing meaning.

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

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

With no output schema, the description carries the burden of explaining returns and does so thoroughly: the field set, the free-vs-full tier split, and what energy_context does and does not contain. Combined with the sibling routing for query_scp, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% and both parameters (actor_name, designation) are already fully documented in the schema, including the ISO code vs partial-name matching and the cross-tool naming note. The description's 'Filter by designation or actor name' adds no syntax or semantics 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?

The description gives a specific verb ('Retrieve') and resource ('whole Sovereign Capability Profile (SCP) actors'), then enumerates the exact fields returned (designation, capability score, severance result, assessed, D1–D7 met/not-met, energy_context). It explicitly names the sibling it is not — 'to pivot one dimension across all actors ... use query_scp' — so an agent can discriminate 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?

It states the primary use ('fetch complete actor records') and names three concrete alternative scenarios (pivot one dimension, compare actors side by side, read the dimension-watch register) that route to query_scp instead, plus the filter options. When-to-use, when-to-use-something-else, and the selecting condition are all explicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior. The description usefully adds that the register is returned in full (no parameterization or partial fetch) and that it is 'a descriptive roster, never inference', clarifying the epistemic nature of the payload beyond the annotation set.

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 the verb and resource, then the payload contents, then the boundary versus get_methodology. It is dense with em-dash-separated clauses and a touch long, but every clause carries information rather than filler.

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

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

With no output schema available, the description carries the return-value burden well: it enumerates fields (bloc assignment, universal category, evidence, source URLs, metadata, snapshot history, changelog, pre-register decisions). Combined with annotations covering safety, an agent has everything needed to call it and interpret results.

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

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

The tool takes zero parameters, so the baseline is 4. The description reinforces this by saying the register is 'served whole', implying no filtering or pagination arguments exist, which matches the empty schema.

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

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

States a specific verb (Retrieve) plus the exact resource (WEO Bloc Membership Register) and enumerates the contents: nations, bloc assignment, membership category, evidence/source URLs, document metadata, sectioned provenance. It clearly distinguishes itself from get_methodology, which is named as the home of category definitions.

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?

Frames the tool as the 'machine mirror of the public blocs register', 'served whole and free', which tells the agent this is an unfiltered full-roster read, and routes the agent to get_methodology for definitions. It stops short of explicit when-not-to-use guidance or naming other roster-shaped alternatives among the siblings.

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, closed world), so the description isn't burdened there. Instead it adds substantive behavior the annotations can't convey: retirement is monotonic ('retired links are never restored', a fresh assessment enters as a new link at the next sequence), tier-dependent field availability, and what the metadata block contains.

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

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

The purpose is front-loaded in the first sentence and the length is largely justified by the lack of an output schema, since the middle passages document the returned fields. It is dense and somewhat exhausting to parse, with long parenthetical chains, but almost every clause carries usable technical information rather than filler.

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

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

With no output schema, the description carries the full return-value burden and discharges it thoroughly: link_type values, attribution, entity, identity/lifecycle fields, tier-gated analytics fields, and the metadata block with status_counts and last_updated. Specifying the default active/retired behavior closes the remaining gap for a zero-required-param 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 the baseline is 3, but the description adds real meaning beyond the schema — concrete actor code examples with the caveat 'GB, not UK' that the ISO alpha-2 schema wording leaves ambiguous, and restates the include_retired semantics in behavioral terms (frozen snapshots).

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 ('Retrieve the event↔dimension membership links') and immediately scopes it to what events qualify or contribute to for each actor's SCP dimensions. It also explicitly differentiates itself from the sibling it is closest to by naming `get_capability_signatures` for the higher-order derivation work.

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 filter options (actor, dimension, event_id), states the default behavior (active links only), explains what `include_retired` is for and when NOT to use it ('to reconstruct a past state, not to read current membership'), and routes to the alternative tool for signatures.

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 cover only the safe-read profile (readOnly, idempotent, non-destructive), yet the description adds substantive behavior: signatures are never edited in place — a member-set change retires the whole signature and a still-qualifying structure re-enters as a new one; active-only by default; and member_links is authoritative while node fields are denormalised and subordinate. This is exactly the extra lifecycle/auth-adjacent context the annotations cannot convey.

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

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

Purpose is front-loaded, but the body is a single dense, jargon-laden run-on that crams the return-field inventory (nodes, legs, dimension span, attribution profile, narrative, member_links, lifecycle fields, metadata) into one sentence. It is informative but hard to parse and repeats schema content, so it is not tightly trimmed.

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

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

With no output schema, the description carries the full return-value burden and does so thoroughly — enumerating signatures, nodes, directional legs, dimension span, attribution profile, member_links, lifecycle fields, status counts and the pre-operational caveat. Nothing an agent needs to interpret results 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 the baseline is 3, but the description adds meaning: omitting signature_id returns the full set with all nested sub-structures, and include_retired is framed as reconstructing a past state given the no-in-place-edit lifecycle. That is meaningful nuance beyond the raw schema text.

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 ('Retrieve') and resource ('precomputed Capability Signatures') and defines the resource positively — directional CC chains/hubs of connection types 1/3/4/5 spanning two or more SCP dimensions. It also distinguishes itself from siblings by naming get_capability_links as the tool for the underlying membership links, so an agent can route correctly 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 clear selecting conditions: omit signature_id for the whole set, pass it (e.g. 'CS-001') for one, pass include_retired to receive retired signatures. It also redirects to get_capability_links for underlying event-dimension membership. It lacks an explicit 'do not use this for X' exclusion beyond that redirect, 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?

Annotations already declare readOnly, idempotent and non-destructive behavior, but the description adds substantial operational context: quantities are never summed, documents are counted once per challenge, history is append-only, figures are dated observations within a Challenge List epoch, and status remains pre_operational until stated conditions are met. It also notes the register is served in full on both tiers. These details go well beyond what the annotations provide.

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 front-loads the core purpose and is information-dense without obvious padding for a complex 10-parameter tool. However, it is a single long paragraph with many clauses and em-dashes, which reduces readability and structure. It could benefit from clearer separation of returns, routing and parameter guidance.

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

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

With no output schema, the description carries the full burden of explaining returns, and it does so thoroughly: challenge table, actor table, records with evidence, Challenge List Reference, and definitions. It also covers caveats about counting, status semantics, and tier availability. Nothing essential for correct invocation 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 description coverage is 100%, so the schema already explains each parameter's meaning, enum values and defaults in detail. The description recaps the parameters (view, filters, record_id, include_history) but adds little semantic value beyond what is already structured, aside from reinforcing that record_id overrides view and that history returns an append-only series. Baseline 3 is appropriate when the schema carries the parameter documentation.

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

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

The first sentence names a specific verb (Retrieve) and a precise resource (the Compute Commitment Register), and immediately defines the register as verified commitments of computing capacity by named actors. It also distinguishes the tool from siblings by naming get_event, query_scp and get_metrics for adjacent use cases. An agent can identify the tool's scope 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?

The description explicitly routes the agent to alternatives: 'for an attributed event use get_event; for sovereign capability use query_scp; for coordination metrics use get_metrics.' It also states the default view and how filters select subsets, giving clear when-to-use guidance. The condition for using each alternative is stated directly.

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 value beyond that: it discloses that the response shape is conditional, returning full evidence on the full tier (or when an endpoint is a sample event) and base fields otherwise. It stops short of naming what the 'base fields' are, keeping it out of the top band.

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 with the purpose front-loaded and the routing hint before the return semantics. Dense jargon ('full tier', 'base fields') costs a little clarity but nothing is wasted.

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

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

With no output schema, the description carries the return-value burden and does explain that evidence depth varies by tier. It leaves 'full tier' and 'base fields' undefined for a reader unfamiliar with the domain model, which is the only real gap for a single-parameter read 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?

One parameter at 100% schema description coverage, so the schema already documents `connection_id`. The description's example ('CC-06-11-3') duplicates the schema example rather than adding new semantics, 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 ('Retrieve') and resource ('a single Coordination Connection (CC)') with the scoping key ('by its connection_id'). It explicitly separates itself from the sibling `get_connections`, so an agent can choose between them 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 an explicit trigger ('Use when you have the exact identifier') and names the alternative plus its condition ('to list or filter CCs, use `get_connections`'). Both the when and the when-not are covered.

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 read-only, idempotent, non-destructive, closed-world operation. The description adds useful behavioral context by explaining the returned fields and the tier-dependent inclusion of evidence summaries, evidence detail, and verification history, though it does not cover pagination or ordering behavior.

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

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

The definition is front-loaded and dense with useful information, with no redundant background. It is slightly long and compound in places, but every sentence contributes either selection guidance or return-value context.

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

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

There is no output schema, so the description carries the return-value burden, and it does explain the core CC fields plus tier-dependent evidence fields. It does not mention pagination, result limits, or ordering, which keeps it from being 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 the description largely restates the filters already documented in the schema: event as source/target, type 1–7, and confidence values. The baseline of 3 is appropriate because the schema carries the parameter semantics.

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

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

The description uses a specific verb and resource ('Retrieve Coordination Connections') and explains what CCs are as typed directional relationships between events. It explicitly distinguishes the single-record sibling `get_connection_by_id`, so an agent can select this tool without opening schemas.

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

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

It states the optional filter dimensions (event as source or target, type, confidence) and explicitly routes single-CC lookups to `get_connection_by_id`. This gives clear when-to-use and when-to-use-the-alternative 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 establish read-only, idempotent, non-destructive, closed-world, but the description goes well beyond them: exact-first then substring matching order, the fallback behavior on an unknown term (returns a sample of available terms), what a hit returns (context, section anchor, deep link), and tier availability. These are behavioral traits an agent cannot obtain from 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?

Front-loaded with the primary action and scoped tightly; every sentence carries information. It is dense and clause-heavy, which slightly taxes first-pass readability, but no sentence is redundant.

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 return-value burden and does so: it lists hit fields, fallback output, and overview fields. For a one-param read tool with full annotations, nothing an agent needs to invoke it correctly 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 coverage is 100% with a single optional param, so the baseline is 3, but the description adds meaning beyond the schema by spelling out what omitting `term` actually yields (phase, activation criterion, corpus size, enquiry address) rather than the schema's terse 'programme overview'.

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 (look up) plus a named resource (WEO Contribution Architecture vocabulary) with concrete example terms and an enumeration of the resource's sub-domains (terms, credit classes, governance provisions). It also explicitly disambiguates from the sibling get_methodology, so an agent can distinguish the two without opening either schema.

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

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

Gives explicit when-to-use ('resolve participation vocabulary'), an alternative with its boundary ('the Methodology Manual (`get_methodology`) governs what qualifies'), and a mode-switch instruction ('Omit `term` for programme status'). Nothing about tool selection is 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 declare readOnly/idempotent/non-destructive/closed-world, so the safety bar is met. The description adds genuinely useful semantics beyond that: counts are computed live, capability link/signature counts exclude retired records, and the active/retired splits live in the capability tools' metadata.

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 scoping note is well placed and the content is signal-dense, but the first sentence is a single sprawling run-on enumerating every distribution dimension. It is hard to parse and could be structured into bullets or split sentences.

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 return-value burden and does so thoroughly: it names every dimension, the ENT/Warmth Engine Ratio, the derived layers, event-ID range, and methodology version. Only the response's actual shape/format 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 are zero parameters, so per the baseline there is nothing for the description to disambiguate at the argument level. It correctly notes 'No parameters', matching the empty schema.

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

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

States a specific verb (retrieve) and resource (corpus statistics) and enumerates exactly what is returned — event/CC/actor distributions, ENT/Warmth Engine Ratio, derived layer counts, methodology version. This is unmistakably different from get_metrics or get_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?

The description conveys that it takes no parameters and computes live figures, implying it is the 'describe present coverage' tool, but it never states when to prefer it over get_metrics, get_topology, or get_methodology. Usage must be inferred.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is free; the description goes further by disclosing tier-gated behavior (free tier returns complete records only for sample events and classification facts otherwise, full tier returns every field) and by defining the semantics of the returned `date` field. It stops short of covering failure behavior for an unknown ID, so it is strong rather than exhaustive.

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

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

Four tight sentences ordered by usefulness: what it returns, when to use it, the ID format, then the tier caveat. The opening field enumeration is slightly listy but each element informs the agent about coverage, so little 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?

With no output schema, the description carries the burden of describing the return payload and does so via the field list plus the free/full tier distinction. Combined with the routing guidance and ID format, an agent has everything needed to call it correctly.

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

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

Only one parameter and schema coverage is 100%, so the schema already documents event_id including the zero-padded format. The description's 'Pass `event_id` as the zero-padded string (e.g. "06", "141")' largely restates the schema rather than adding new meaning — correct baseline.

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

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

States a specific verb+resource (retrieve one event by ID) and enumerates exactly what the record contains (classification, assessment, sources, industry tags, ENTs, bloc analysis, tier rationale). It is clearly distinguishable from the sibling get_event_stack and from search_events.

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

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

Explicitly states the precondition ('Use when you already hold an event ID') and names the alternative for the opposite case ('to find IDs, use `search_events`'). No inference is required to pick between the two 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 read-only/idempotent/non-destructive, but the description adds real behavioral context beyond them: it is a derived view over existing substrates, each substrate 'keeps its own gating,' the free tier 'leaks no paid fields,' the capability array carries active links only and takes no widening parameter, and the three arrays are 'never merged' because they are different kinds of claim.

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 core purpose in the first clause before diving into the three-array breakdown, and every subsequent sentence carries meaning (array contents, distinctions, alternatives). It is dense and long, but not padded with redundant restatement.

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 fully describes the return shape (three named arrays with their per-item fields), the gating/visibility model, and the alternatives for related queries. An agent has everything needed to call it correctly and interpret results.

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

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

Only one parameter and schema coverage is 100%, so the schema already documents the event_id semantics fully. The description adds a little framing ('the event's neighbourhood as the corpus now stands') and 'Pass event_id,' but no format or syntax beyond the schema. 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 (assemble) and resource (the stack journey for one event), then enumerates the three arrays returned. It explicitly names sibling tools (get_threads, traverse_coordination, get_capability_links) so an agent can distinguish this tool from them without opening any schema.

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

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

Gives explicit when-to-use alternatives: 'For the material layer alone, use get_threads; for the directed multi-hop coordination lineage between events, use traverse_coordination,' and 'for retired memberships, use get_capability_links with include_retired.' These are concrete routing conditions with named 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 cover the safety profile (readOnly, idempotent, non-destructive). The description goes beyond them by disclosing matching behavior (exact-first, then substring) and the fallback for unknown terms, which is genuinely useful operational context.

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

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

Three front-loaded sentences: purpose, return shape, usage and matching. Every sentence carries distinct information with no redundancy.

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

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

With no output schema, the description still enumerates the return contents (definition, section anchor, deep link, methodology version) and matching semantics. Nothing an agent needs to call it correctly 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 coverage is 100% so the `term` parameter is already documented. The description adds value beyond the schema by explaining the matching algorithm and the unknown-term fallback, which the schema does not capture.

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 ("look up the WEO methodology definition") and enumerates concrete example terms, making clear it is a glossary/lookup tool distinct from the data-retrieval siblings. An agent can immediately tell this resolves vocabulary rather than fetching 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?

"Use to resolve any vocabulary the other tools return" gives explicit context for when this tool is appropriate and ties it to the sibling set. It does not name a competing alternative or an explicit when-not, but no real alternative exists for glossary lookup.

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 the description adds substantial context beyond them: the pre-operational caveat, the per-metric `status` vocabulary (published / pre_operational / insufficient_corpus), the taxonomy-epoch comparability constraint, and the derived-not-live distinction. This is the kind of nuance an agent cannot infer from 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?

Dense and front-loaded: the return payload is described first, then routing, then behavioral caveats. Some material (the `metric`/`include_history` guidance) duplicates the schema, and the status explanation is slightly repetitive, but there is no filler prose.

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 return-shape burden and does so: it lists every metric, explains the sparse matrix layout and fixed row order, and documents the `status` field. For a read-only metrics endpoint it leaves no operational gap.

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

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

Schema coverage is 100%, so both parameters are already fully documented in the schema. The description largely restates the same semantics (omit `metric` for all; `include_history` for the full series) without adding format or edge-case detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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 ('Retrieve the WEO quantitative coordination metrics') and enumerates the exact metric set returned (CSTF, transmission matrix, FFD, CBCF, CGR). It explicitly differentiates itself from the sibling get_coverage_stats, so an agent can route 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?

Names the alternative tool and the condition that selects it ('For live corpus counts and distributions, use get_coverage_stats'), plus concrete invocation guidance: omit `metric` for all, set `include_history` for the full series. Both the when and the how are covered.

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, closed-world), so the description earns credit by adding data semantics: what a thread is not, the enumerated linkType vocabulary (deploys | trains_on | powered_by | fabricated_at), and that it is free on both tiers. It does not address result size or limits when `event_id` is omitted for the entire layer, which is a meaningful gap for an unbounded query.

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

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

Purpose is front-loaded in the first clause, followed by disambiguation, usage modes, and the sibling pointer in a logical order. It is dense but nearly every sentence carries information; the 'Free on both tiers' note is minor but useful.

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 appropriately describes what each link carries (sourced claim, linkType, asset, host-event field) and how to scope the query, which is enough to call it correctly. The only omission is any indication of pagination or volume behavior for the whole-layer 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?

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema's brief note by explaining the directional meaning of the results for a given event_id and confirming that omitting it returns the whole layer, adding interpretive value the schema does not carry.

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 ('Retrieve Infrastructure Threads') and immediately defines the resource as the material-link layer where a named AI hardware asset appears as a documented fact in two events. It explicitly distinguishes this from 'Coordination Connection' ('no connection type, no confidence grade'), so an agent can separate it from get_connections without opening either schema.

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

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

Gives explicit routing: pass `event_id` for bidirectional linked events (outbound = assets this event deploys/trains on; inbound = events using this event's asset), omit it for the whole layer, and use `get_event_stack` instead for a single event's value-chain stack. Both the when and the alternative are named.

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 substantive context beyond that — the concrete statistics returned, the filter behavior, and the note that 'the full tier adds the held analyst layer', which hints at tier-dependent results. It does not cover pagination or response size limits, so it falls 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?

Dense but well-structured, with the core purpose and the omit/pass branching front-loaded ahead of the alternative-tool routing and the tier note. It is longer than strictly necessary — the enumeration of per-node metrics could be trimmed — but nearly every sentence carries routing or semantic value.

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

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

With no output schema, the description correctly carries the burden of describing return content, covering both the whole-graph summary and the per-node metric list, and it clarifies filter effects. Nothing essential for correct invocation 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% so the baseline is 3, but the description adds real meaning beyond the schema: the semantics of omitting node_id (whole-graph statistics) versus supplying it (per-node structural metrics), plus the enumerable metric set per node and per-graph. The class/cc_type/min_reach filters are grouped and explained as node-matching filters.

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 ('Retrieve the precomputed Coordination Topology') and immediately defines the underlying structure (structural lineage layer over the parent→child Coordination Connection DAG). It differentiates itself from siblings by name (traverse_coordination, get_event_stack), so an agent can pick it without opening schemas.

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

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

Explicit branching guidance: omit node_id for whole-graph stats, pass node_id (with example 'E34') for single-node metrics. It also names two alternative tools and the exact conditions under which to prefer them, leaving nothing 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, closed world), and the description adds genuinely new context: results are 'descriptive — recorded status and fields, never causal inference,' free tier returns only met + headline with a US sample, full tier adds per-dimension evidence, and omitting all params returns a usage hint.

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?

Effectively one dense but front-loaded paragraph that leads with purpose and sibling differentiation, then enumerates the three modes, then the output semantics and tiering. No sentence is filler; em-dash clauses carry the routing and return-shape information compactly.

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 return-shape burden and does so for all three modes plus tier differences and default behavior. Combined with annotations covering the safety profile, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so baseline would be 3, but the description goes further: it explains what each mode actually produces (pivot one dimension across every actor with met status and basis; side-by-side D1–D7 comparison; the dimension_watch fields of actor, dimension, current vs expected_change, trigger, timeline) and encodes the mutual-exclusivity constraint that additionalProperties:false alone does not express.

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 ('Query the Sovereign Capability Profile (SCP) register') and immediately distinguishes itself from get_actors, which 'fetches whole actors' and is 'where energy_context is served; it is not returned here.' An agent can route between the two 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?

States the selection rule explicitly — 'Pass exactly one of' — and gives the condition that selects each mode: dimension pivots across actors, actors compares D1–D7, watch:true switches to the dimension_watch register. It names the alternative sibling (get_actors) and what that sibling does differently.

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 a safe, idempotent, closed-corpus read, so the bar is lower, yet the description still adds substantive behavior no structured field carries: the verification lag (six months; 60 days for verified product releases) and the tier-dependent field availability (free tier withholds assessment/evidence on non-sample events). These are real behavioral traits an agent must know to interpret results.

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 purpose and return shape, then routing, then the lag caveat and tier behavior — every sentence carries information and none is filler. It is dense and slightly long for a single paragraph, but not padded, so it sits just under a perfect mark.

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

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

There is no output schema, and the description compensates by describing what is returned (matching events plus metadata, bounded by `limit`), how completeness is constrained (verification lag), and how results differ by tier. Nothing essential for correct invocation or result interpretation 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% and all seven parameters, including the five enums, are documented in the schema itself with cross-references between `bloc` and `tier`. The description restates the filter names and the limit default/max but adds no syntax, format, or combination semantics 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 a specific verb and resource ('Search and filter the WEO event corpus') and enumerates the filter dimensions (bloc, tier, domain, event type, industry tag) plus the return shape (matching events with metadata, capped by limit). It also explicitly distinguishes itself from the sibling `get_event`, so an agent can route 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 an explicit when-to-use ('discover or shortlist events') and names the alternative and its condition ('for a single event's complete record, use get_event'). It goes further by warning that a recent event may be absent due to the verification lag and that an empty result is not evidence of non-occurrence, which is exactly the kind of usage guidance that prevents misinterpretation.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral detail beyond that: it discloses the ignored_params echo when homogeneous_only is sent to an adjacency mode, the resolved_node_id echo for bare numeric ids, and that a node with no backbone edges is reported distinctly rather than as unknown. It does not discuss result size or any caps on the number of paths returned.

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

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

Purpose and mode semantics are front-loaded, then parameter interactions, then id-resolution behavior. Dense but every clause carries information (mode contracts, scope of filters, ignored-param behavior); no filler sentences.

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, but the description compensates by describing what each mode returns (paths with CC-type sequences and pure-lineage flag, reachable nodes, direct parents/children) plus the echoed fields. For a 7-parameter graph-walk tool this is close to complete; only result-size limits or empty-result semantics are 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%, so the baseline is 3, but the description adds cross-parameter semantics the schema cannot express: cc_types and max_depth apply to path AND adjacency walks, homogeneous_only is path-only and is echoed in ignored_params otherwise, and a bare node_id is resolved to the canonical E-prefixed form. That is meaningful meaning beyond the per-field descriptions.

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

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

States a specific verb (walk) and resource (Coordination Topology lineage graph) and enumerates the four modes with what each returns. It also explicitly separates itself from the sibling get_topology ('For a node's structural metrics or the whole-graph summary rather than walks, use get_topology'), so an agent can route between the two 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?

Names the alternative tool and the exact condition that selects it, and explains which mode to pick for each intent (path vs ancestors/descendants vs neighbours). Nothing about when to use this versus get_topology is left to inference.

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