Warmth Engine Observatory

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

Annotations already declare readOnly, idempotent, non-destructive, non-open-world, so safety is covered. The description adds substantive behavioral context: free tier returns only met status and headline (plus US sample in full), full tier adds constraint/qualification/sources, and energy_context is served in full on both tiers. It also clarifies the data is descriptive recorded status, never inference. Minor gap: no pagination/return-format note.

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 core purpose and the sibling routing. The energy_context explanation is long and somewhat tangential, but it is scoping-relevant (external reference data outside the analytical stack), so it earns most of its place. Slightly verbose overall.

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 describing return contents, and it does so thoroughly (field-by-field enumeration plus tier-dependent richness). It also clarifies provenance of energy_context. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100% and both params (actor_name, designation) are documented in the schema itself, so baseline 3 applies. The description restates the filters ('Filter by designation or actor name') without adding syntax or format beyond what the schema already provides.

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

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

States a specific verb ('Retrieve') and resource ('whole SCP actors') and enumerates the exact fields returned (designation, capability score, severance result, assessed, D1–D7 met/not-met, energy_context). It explicitly distinguishes itself from the sibling query_scp, so an agent can tell them apart without opening either schema.

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

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

Names the alternative explicitly ('to pivot one dimension across all actors, compare actors side by side, or read the dimension-watch register, use `query_scp`') and gives the selecting condition (fetch complete actor records). Clear when-to-use and when-to-use-something-else.

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 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 readOnly/idempotent/non-destructive, so safety is covered. The description adds real value beyond that by disclosing the returned payload shape — id, source/target event IDs, type name+number, confidence, direction — and the tier/evidence-detail escalation, which matters given 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?

Front-loaded with the core retrieval statement, then filters, then the sibling redirect, then the return-shape note. Dense but every clause carries information; slight overload in the final return-shape sentence keeps it from a perfect score.

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

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

For a read-only, three-filter list tool with no output schema, the description covers what it returns, how to filter, and where to go for a single record. It omits pagination or result-size behavior, which is a minor gap rather than a blocking one.

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 already documented in the schema. The description restates the filter semantics (event as source or target, type range, confidence codes) but adds no syntax, defaults, or combination rules beyond it, 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?

Names a specific verb and resource and defines the resource inline ('Coordination Connections (CCs) — the typed, directional relationships WEO records between events'). It also explicitly routes the single-record case to get_connection_by_id, so it is distinguishable from both siblings and generic list tools.

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

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

States the available filters (event as source or target, type 1–7, confidence tier) and names the alternative tool for the single-record case. It does not say when this tool is a poor choice or what happens with unfiltered calls, but the routing guidance is clear.

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

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

Annotations already 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 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, non-openWorld, so the safety profile is covered. The description adds real behavioral context beyond that: the data is precomputed, what each return mode contains (taxonomy counts, roots, multi-parent nodes, weakly-connected components; depth, betweenness, fan-in/out per node), and that a full tier adds a held analyst layer. It does not discuss staleness/refresh or auth, 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?

Front-loads the core purpose and the omit/pass decision before the sibling routing and filter notes. Dense but every clause carries information; the metric enumerations are long but necessary given no output schema. Minor density cost keeps it off 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 carries the return-value burden and does so fully (enumerated metrics per mode plus tier distinction), while annotations handle safety. An agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further: it explains the presence/absence semantics of node_id (omit = whole-graph, include = single node with example 'E34') and clarifies that class/cc_type/min_reach act as node filters returning matching nodes. That is meaningfully more than the raw 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?

Names a specific verb (Retrieve) and resource (Coordination Topology), defines the underlying structure (DAG lineage over the parent→child Coordination Connection graph), and explicitly distinguishes itself from two siblings (traverse_coordination, get_event_stack). An agent can route correctly 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 branching guidance: omit node_id for whole-graph statistics, pass node_id for single-node metrics, and points to traverse_coordination for actual paths and get_event_stack for an event's value chain. This is textbook when-to-use plus 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, 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 carry readOnly/idempotent/no-destructive, so safety is covered; the description goes further with behaviors found nowhere else: bare numeric node_id resolution echoed as resolved_node_id, an edge-less-but-existing node reported distinctly from unknown, and out-of-scope params surfaced in ignored_params rather than silently dropped. This is exactly the extra context that prevents misuse.

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 core action and DAG scope, and every clause conveys mode behavior, filter applicability, or edge-case handling. It is a single dense paragraph with stacked parentheticals, which is slightly harder to scan, but there is no filler to cut.

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 7-parameter, four-mode traversal tool with no output schema, the description covers return shape per mode (paths with CC-type sequence and purity; reachable nodes; direct parents/children), filter interactions, and input normalization. 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%, so the baseline is 3; the description adds genuine meaning by stating that cc_types and max_depth apply to both path and adjacency walks ('runs a bounded typed walk over the backbone edges'), what the path results contain per path, and that homogeneous_only is path-only with ignored_params echoing. Much of that is mirrored in the schema text, so it is strong value-add rather than fully novel.

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+resource: 'Walk the Coordination Topology lineage graph (precomputed lookups over the parent→child Coordination Connection DAG)' with the four modes enumerated inline. It explicitly distinguishes itself from the sibling get_topology ('for structural metrics or the whole-graph summary rather than walks, use get_topology'), so an agent can route without opening a schema.

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

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

Gives an explicit when-not rule with the named alternative (get_topology for metrics/summary), and mode-by-mode scope so the agent picks path vs ancestors/descendants/neighbours correctly. Also states which filters apply to which mode, removing inference.

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