Warmth Engine Observatory

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

No annotations are provided, so the description carries the full burden. It discloses return content, free/full tier differences, the nature of energy_context as external reference data, and the key behavioral caveat 'Descriptive — recorded status, never inference.' This goes well beyond a bare 'get' and gives the agent an accurate model of what the tool returns and what it does not.

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

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

The description is long, but its length is justified by the need to explain free/full tier behavior and the nuanced external-reference nature of energy_context. It is front-loaded with the core purpose and field list, then moves to usage guidance and caveats. A few sentences are dense, but each adds useful information.

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

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

For a tool with two optional parameters, no output schema, and no annotations, this description is remarkably complete. It defines returned fields, filtering behavior, tier differences, external data provenance, and when a sibling should be used instead. Nothing essential for correct invocation or 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%, so the schema already documents actor_name and designation well. The description's 'Filter by designation or actor name' mostly restates the schema rather than adding new semantic detail. Baseline 3 is appropriate because 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?

The description opens with a specific verb and resource: 'Retrieve whole Sovereign Capability Profile (SCP) actors' and enumerates exactly what a record contains. It also distinguishes itself from query_scp by naming the alternative and its different use cases, making sibling differentiation explicit.

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 explicitly states when to use this tool ('fetch complete actor records') and when to use the sibling instead ('to pivot one dimension across all actors, compare actors side by side, or read the dimension-watch register, use query_scp'). Tier behavior for free versus full tier is also explained, giving an agent concrete selection criteria.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that the tool serves the entire register ('Served whole'), is free, is a machine mirror of a public register, and is descriptive rather than inferential. This gives the agent a clear model of the tool's scope and side-effect-free nature.

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

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

Two dense, front-loaded sentences cover the resource, the full content of the response, the delivery mode, the non-inferential nature, and the relevant sibling tool. Every clause earns its place; there is no filler or repetition.

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

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

Given there is no output schema, the description compensates by listing the major content categories a caller should expect: nations, assignments, categories, evidence, URLs, metadata, and provenance sections. It is sufficiently complete for a parameterless retrieval tool, though exact field-level shape is not specified.

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 has zero parameters, so the baseline is 4 and the description does not need to explain argument semantics. The description reinforces that no filtering or configuration is possible by emphasizing that the register is served whole.

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 opens with a specific verb and resource ('Retrieve the WEO Bloc Membership Register') and then enumerates exactly what the tool returns: nations, bloc assignments, membership categories, evidence, source URLs, metadata, and provenance. It actively distinguishes itself from get_methodology by stating that category definitions are served there.

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 usage context is clear: this tool serves the whole register and is appropriate for retrieving bloc membership facts. It explicitly routes the user to get_methodology for category definitions and warns that it is 'a descriptive roster, never inference,' which helps the agent avoid using it for analytical or definitional tasks.

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

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

With no annotations provided, the description carries the full disclosure burden and does so thoroughly. It explains active-by-default behavior, that retired links are never restored, that fresh assessments create new links rather than mutating old ones, and details the lifecycle fields including status_changed. It also clarifies that sole-vs-multiple basis must be derived by counting rather than assumed from a flattened flag.

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

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

The description is long, but every section earns its place given the tool's complexity and the absence of an output schema. It is front-loaded with purpose and filtering, then moves through link fields, lifecycle, defaults, metadata, and finally the sibling pointer. It could be tightened, but the structure is logical and dense with necessary information.

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

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

For a complex tool with no output schema and no annotations, the description leaves almost nothing ambiguous: it covers link semantics, field meanings, lifecycle behavior, default and archive modes, metadata contents, and the alternative tool. The only minor omitted detail is whether multiple filters combine with AND or OR, but this is not enough to reduce completeness given the overall richness.

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 genuine value beyond the schema: it gives concrete actor examples with the important GB-not-UK warning, defines link_type and attribution semantics, and reframes include_retired as a way to reconstruct past state rather than a simple boolean toggle. The description does not over-explain what the schema already documents, but it adds enough to justify a 4.

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 opening sentence states a specific verb and resource: 'Retrieve the event↔dimension membership links' for SCP capability dimensions. It clearly distinguishes itself from the sibling tool by ending with 'For the higher-order signatures built from these links, use get_capability_signatures.' An agent can immediately identify what this tool returns and how it differs from the most similar alternative.

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 says to filter by actor, dimension, or event_id and explains when to pass include_retired: 'use this to reconstruct a past state, not to read current membership.' It also names the alternative tool for higher-order signatures, so an agent knows when not to use this one. This is strong, actionable routing 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?

With no annotations, the description carries the full burden, and it excels: it discloses that signatures are never edited in place, that changes retire the whole signature, that active signatures are the default, that `member_links` is authoritative while node fields are denormalized, and that a caveat exists for pre-operational data. This gives the agent a reliable model of side effects, defaults, and data provenance.

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

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

The description is information-dense and technically precise, but it is quite long and some phrasing adds little actionable value, such as 'corroborating structural texture rather than a headline finding' and 'served in full and free.' While the length is defensible for a complex domain, the structure could be tighter and more front-loaded around selection and behavior.

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

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

Given no output schema, the description thoroughly enumerates what will be returned: nodes, directional legs, dimension span, attribution, lifecycle fields, metadata, status counts, the pre-operational caveat, and non-signature clusters. It also addresses how to resolve `member_links` via `get_capability_links`, making the tool effectively callable in a broader workflow.

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%, but the description adds real interpretive value beyond the schema: it explains the result of omitting `signature_id`, defines retired signatures as frozen whole-state snapshots, clarifies default active-only behavior, and describes how `include_retired` enables reconstruction of past states. This goes well beyond the schema's basic 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?

The description opens with a specific verb ('Retrieve') and a well-defined resource ('precomputed Capability Signatures'), then distinguishes the object from related concepts like Capability Links and directional CC graph structures. It clearly differentiates this tool from siblings such as get_capability_links by positioning this as the signature-level view.

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 gives explicit usage paths: omit `signature_id` for the full set, pass it for one signature, and pass `include_retired` for retired signatures. It also explicitly routes the agent to `get_capability_links` for underlying membership links, which is an effective alternative. It does not, however, contrast this tool with all nearby structural siblings such as `traverse_coordination` or `get_topology`.

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?

No annotations are provided, so the description carries the full burden. It discloses conditional return behavior (full evidence on full tier or sample events, otherwise base fields only). However, it does not address side effects, error conditions, or authentication requirements. Given the read-only implication of 'Retrieve', the description adds some context but is not comprehensive.

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

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

Two sentences with zero waste. The purpose is front-loaded, and the alternative routing is included. Every clause earns its place, making it highly efficient.

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

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

For a simple get-by-ID tool with one parameter and no output schema, the description explains the return differentiation (full evidence vs base fields) and directs to the listing alternative. It does not mention error handling or not-found scenarios, but such details are often implicit for retrieval tools. Overall, it is sufficiently complete for the tool’s complexity.

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

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

Schema coverage is 100% with the connection_id parameter already described with an example format. The description repeats the example but does not add additional meaning beyond the schema. This matches the baseline 3 for high coverage.

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

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

The description clearly states the tool retrieves a single Coordination Connection by ID, and differentiates it from the sibling get_connections for listing/filtering. The verb 'Retrieve' and resource 'Coordination Connection' are specific and unambiguous.

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

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

Explicitly instructs to use when the exact identifier is known and directs to get_connections for listing/filtering. This gives clear when-to-use/alternative guidance, 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?

With no annotations and no output schema, the description carries the burden of explaining behavior, and it does so well by listing the returned fields and the tier-dependent addition of evidence summary, evidence detail, and verification history. It does not mention pagination or result-size behavior, 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?

The description is appropriately sized for a filtered list operation and front-loads purpose before details. It is dense but not padded; only the tier-dependent clause adds moderate complexity, but it is relevant and earns its place.

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

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

Given no output schema, the description does a strong job covering what results contain and how tier changes the payload. It does not explicitly state default behavior when no filters are supplied or whether results are paginated, so an agent still has minor uncertainty.

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

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

Schema description coverage is 100%, so the input schema already documents all three parameters. The description reinforces the semantic role of each filter but adds little beyond what the schema states, meriting the baseline score.

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 ('Retrieve') with a precise resource ('Coordination Connections') and immediately distinguishes the list-oriented query from the single-record sibling, get_connection_by_id. It also names the entity relationship and optional filters, making the tool's scope unmistakable.

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 explicitly states when to use the single-record alternative ('For a single CC by its identifier, use get_connection_by_id'), which is clear routing guidance. It also enumerates the optional filter dimensions, giving an agent enough context to decide whether this tool fits a request.

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

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

With no annotations, the description carries the behavioral burden, and it does so well: it discloses return contents, exact-first then substring matching, unknown-term handling with a sample of available terms, and tier availability. It stops short of describing the full response format or any access/error details, hence not a 5.

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

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

The description is dense and front-loaded, with the core purpose first. Each sentence contributes useful information, though the six-sentence length and multiple parentheticals make it slightly heavier than strictly necessary.

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

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

For a one-optional-parameter lookup with no annotations and no output schema, the description is complete: it covers optional invocation, returned data, matching semantics, unknown-term behavior, and the relationship to the sibling tool. An agent has enough 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?

The schema already documents the optional `term` parameter with examples and the omit-for-overview behavior, so the baseline is 3. The description adds meaningful operational meaning by explaining matching behavior and unknown-term fallback, going beyond the 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?

The description states a specific action ('Look up WEO Contribution Architecture vocabulary') and clearly identifies the resource and scope. It also differentiates this tool from its sibling get_methodology by noting the CA governs participation while the Methodology Manual governs what qualifies.

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 explicitly says when to use the tool ('Use to resolve participation vocabulary') and names the alternative ('get_methodology') with the distinction between participation and qualification. It also gives concrete invocation guidance: omit `term` for programme status.

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

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

With no annotations, the description carries the full behavioral burden and meets it: it discloses that figures are computed live, that Capability Link/Signature counts are active records only, that retired records are excluded, that the active/retired splits live in the capability tools' metadata, and that the secondary-industry breakdown is full-tier only. This gives an agent an accurate model of what the call will and will not report.

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

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

The description is dense and front-loaded with the verb and primary object, and every clause carries distinct information rather than filler. It is, however, one long em-dash-heavy run-on that could be easier to parse if the enumerated output dimensions were structured; still, 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?

Given no output schema and high conceptual complexity, the description is thorough: it enumerates the full set of returned statistics, the derived layers, the special ENT/Warmth Engine Ratio value, the event-ID range, the methodology version, plus exclusions and caveats. An agent can invoke the tool and interpret the response without needing additional documentation.

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

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

There are zero parameters and schema coverage is 100%, so the baseline is 4. The description adds a behavioral clarification—'No parameters; figures are computed live'—which reinforces that invocation requires no input, but there is no parameter meaning to elaborate on.

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 opens with the specific verb 'Retrieve' and names an unambiguous resource: 'current corpus statistics' with live counts and distributions. It enumerates the exact dimensions and derived layers (Threads, Capability Links, Capability Signatures, ENT statistics, event-ID range, methodology version), which makes it unmistakably distinct from the sibling entity-retrieval tools even without naming them.

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 implies its own use case—a live overview of corpus coverage—by describing what it returns, but it never explicitly states when to choose it over siblings like get_metrics or get_methodology. The only alternative-reference is the pointer to the two capability tools' metadata for active/retired splits, which is a helpful nuance but not a general usage rule.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It does so well by explaining the free-tier vs full-tier difference ('complete record for sample events... classification facts for all others... deeper assessment and evidence withheld'). The read-only nature is implied by 'Retrieve', though not stated as explicitly as with a readOnly annotation.

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

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

The description is information-dense but every sentence earns its place: the purpose, the content returned, the routing guidance, the ID format, and tier-based behavior. It is front-loaded with the core action and avoids filler.

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

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

For a single-parameter lookup tool with no output schema and no annotations, this description covers everything an agent needs to call it correctly: what fields come back, how to format the ID, when to use it, and how the response varies by tier. No critical gap remains.

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 schema already documents the event_id parameter as a zero-padded string with examples. The description repeats this guidance but adds no new meaning about the parameter beyond what the schema provides. The baseline of 3 applies.

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

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

The description opens with a specific verb and resource: 'Retrieve one event by ID', and enumerates the record contents (classification, assessment, sources, industry tags, ENTs, bloc analysis, tier rationale). It distinguishes itself from search_events by clarifying this is a direct lookup rather than a discovery tool.

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 when you already hold an event ID; to find IDs, use `search_events`' is an explicit, actionable usage rule. It tells the agent the exact condition for calling this tool and names the sibling to use instead. No inference is required.

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

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

With no annotations at all, the description carries the full burden, and it delivers: it specifies the three-array, never-merged return shape, distinguishes the epistemic status of threads vs CCs, notes the capability array is active-only, and explains the tool is a derived view whose substrates keep their own gating and leak no paid fields on the free tier. This goes well beyond what the schema expresses.

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

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

The description is long but every sentence earns its place: it front-loads the purpose in the first line, uses labeled inline details for the three arrays, and closes with routing alternatives. Without an output schema, this density is necessary rather than padded.

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 tool with one parameter, no output schema, and no annotations, the definition fully covers what returns come back, the meaning of each array, access/gating semantics, and the exact alternatives. Nothing an agent needs to decide whether to call it or interpret its result 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?

The input schema already describes event_id fully, including an example ('196'), so the description adds little semantic value; it merely echoes 'Pass event_id.' With 100% schema coverage, baseline 3 is appropriate.

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

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

The opening sentence states the specific operation ('Assemble the stack journey for one event') and resource (kind-labelled value-chain neighbourhood at depth 1), so an agent can see exactly what the call does. It also distinguishes itself by naming sibling tools for related but narrower tasks (get_threads, traverse_coordination, get_capability_links), making the identity unmistakable.

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 gives explicit routing conditions: use get_threads for material layer alone, traverse_coordination for multi-hop coordination lineage, and get_capability_links with include_retired for retired memberships. It also states that the capability array deliberately takes no widening parameter, telling agents when not to expect broader behavior.

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

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

With no annotations, the description carries the behavioral disclosure burden. It explains matching behavior ('exact-first, then substring') and the unknown-term fallback ('returns a sample of available terms'), plus what the response includes. It does not cover potential errors or case-sensitivity, but it gives materially useful behavioral detail beyond the 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?

Three sentences with no filler; the purpose, examples, output summary, and matching behavior are all included efficiently. It is front-loaded with the primary action and resource before diving into details.

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 single-parameter lookup with no output schema, the description covers the input semantics, the output contents (definition, section anchor, deep link, version), and edge-case behavior. Nothing critical is missing for an agent to select and invoke the tool 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 the baseline is 3, but the description adds meaningful parameter semantics: it gives examples and spells out matching semantics (exact-first, substring, unknown-term sample). This goes beyond the schema's simple 'The term to look up' description.

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

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

The description states a specific verb ('look up') with a clear resource ('WEO methodology definition') and object ('platform-specific term, field, or concept'), and provides concrete examples. It also differentiates the tool from its data-returning siblings by framing it as the vocabulary resolver for terms other tools return.

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 gives clear context: 'Use to resolve any vocabulary the other tools return,' which tells an agent when this tool is the right choice. It does not explicitly name alternatives or state when not to use it, but the guidance is sufficient for the single-term lookup case.

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

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

With no annotations to carry the safety/behavior profile, the description goes deep: results are dated observations, not live recomputations; each metric has a status with three possible values; comparability is restricted to a taxonomy epoch; data is append-only; and it's clearly marked pre-operational. This fully compensates for the missing annotations and adds meaningful context an agent needs before trusting the output.

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?

Every sentence earns its place: the purpose is front-loaded, the sibling distinction follows, then parameter usage, pre-operational caveat, status semantics, comparability constraint, and tier availability. Though dense, it is well-organized and omits redundant 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?

Despite no output schema, the description covers return contents, behavioral caveats, parameter options, and the alternative tool. An agent has everything needed to decide whether to call this tool, how to parameterize it, and how to interpret the results — a genuinely complete definition for a complex metrics endpoint.

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. The description mostly echoes the schema ('Omit metric for all of them') and adds no fundamentally new meaning for either parameter, though it reinforces the append-only behavior of include_history.

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?

Description opens with a specific verb ('Retrieve') and a clearly named resource ('WEO quantitative coordination metrics'), then itemizes the exact metrics returned (CSTF, transmission matrix, FFD, CBCF, growth rate). It also distinguishes itself from get_coverage_stats by contrast, so the agent can tell them apart without inspecting other tools.

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

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

Explicitly names the alternative tool and the condition that selects it: 'For live corpus counts and distributions, use get_coverage_stats — metrics here are derived, dated observations, never live recomputations.' It also instructs on parameter usage ('Omit metric for all of them; set include_history for the full append-only series'), leaving no ambiguity about when and how to call.

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?

No annotations are present, so the description carries the full burden, and it does so thoroughly. It explains what a thread is and is not, the linkType values (deploys, trains_on, powered_by, fabricated_at), bidirectional traversals, and behavior when event_id is omitted. It even notes pricing ('Free on both tiers').

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

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

The description is dense and long but every sentence adds semantic value for a complex concept. It is well-structured with clear definitions, mode explanations, and an explicit alternative. Slight trimming of the linkType enumeration could improve readability, but no information 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 still explains what each link carries, the linkType values, and the global vs per-event behavior. It stops short of describing the exact response shape or pagination, but for a single optional parameter and read-only intent, the agent has enough context to call and interpret the tool confidently.

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

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

Schema coverage is 100% and the schema already provides an example and the omission behavior. The description adds value by explaining how event_id selects inbound vs outbound traversal and by characterizing values like '182' as deployer and '196' as producer, which is meaningful beyond the schema alone.

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

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

The description names a specific resource ('Infrastructure Threads'), defines it as the 'factual material-link layer', and differentiates it from Coordination Connections. This lets an agent distinguish the tool from get_connections and get_event_stack 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?

The description gives explicit invocation modes: pass event_id for inbound/outbound links for a single event, or omit it for the whole layer. It also names the sibling alternative get_event_stack for value-chain stacks, making selection guidance unambiguous.

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

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

With no annotations, the description carries the full disclosure burden. It reveals that the tool returns a precomputed structural layer, which implies read-only access, and it details what each call mode returns. However, it does not mention data staleness from being precomputed or any other behavioral caveats such as performance or error semantics.

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

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

The description is dense but well organized: it front-loads the resource, then covers the two call modes, alternatives, filters, and the extended tier. Every sentence contributes meaningful guidance, and there is no fluff or redundant repetition of the schema.

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

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

Even without an output schema, the description enumerates the return categories for whole-graph and single-node calls, names the sibling tools for related operations, and explains the optional filters. This gives an agent enough context to invoke the tool correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics by linking node_id to per-node structural metrics and explaining that class, cc_type, and min_reach are filters that return matching nodes. It also clarifies that cc_type concerns backbone parent→child edge types.

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 opens with 'Retrieve the precomputed Coordination Topology,' identifying a specific verb and resource, and immediately distinguishes this tool from traverse_coordination and get_event_stack. This makes its role clear even among many sibling 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?

It explicitly states when to use alternatives: use traverse_coordination for actual paths and get_event_stack for value-chain stacks. It also explains two invocation modes—omitting node_id for whole-graph stats vs passing node_id for per-node metrics—so an agent knows how to choose.

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

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

With no annotations, the description carries the full behavioral burden. It explains the output contents of each mode, the free-versus-full tier differences, and the important constraint that readouts are descriptive and 'never causal inference.' It does not mention pagination, rate limits, or explicit side-effect statements, but the query nature and mode-specific output lists make behavior reasonably transparent.

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

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

The description is dense but every clause earns its place: mode definitions, sibling differentiation, output scope, tier behavior, and a fallback. It front-loads the core purpose and then methodically walks through modes without repetition.

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

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

Given there is no output schema and no annotations, this description is unusually complete: it defines all modes, their outputs, the distinction from get_actors, data tier implications, and the no causal inference guarantee. An agent has enough information to select and invoke the tool correctly for any of the three modes.

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?

Although the schema covers parameter descriptions 100%, the tool description adds essential semantics: the requirement to pass exactly one of dimension, actors, or watch:true, example values, and what each parameter returns. It also clarifies that omitting all three yields a usage hint, which is not inferable from the schema alone.

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 opens with a precise verb and object: 'Query the Sovereign Capability Profile (SCP) register by pivoting and comparing.' It names the sibling tool get_actors and explicitly contrasts the two, so an agent can immediately identify what this tool uniquely does.

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 when to use each of the three invocation modes and explicitly excludes get_actors as the place where energy_context is served, with 'it is not returned here.' It also tells the agent to omit all three parameters for a usage hint, leaving no ambiguity about how to invoke the tool.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses important tier-dependent behavior: free tier returns classification facts but withholds deeper assessment and evidence on non-sample events, while full tier and sample events return every field. It also discloses the limit cap.

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

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

The description is two dense sentences with no filler. It front-loads the purpose and filter options, then adds usage guidance and tier-specific behavior. Every sentence earns its place.

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

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

The description covers search scope, filter dimensions, result cap, usage context, the alternative for full single-event records, and tier-based return differences. Given the rich parameter schema and no output schema, this is sufficient for an agent to select and invoke the tool 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%, so the schema already documents all seven parameters. The description adds useful framing by grouping parameters into query text and classification, but it does not materially extend the semantic meaning beyond what the schema provides.

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

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

The description clearly states the verb 'Search and filter' and the resource 'WEO event corpus', then enumerates the filter dimensions: query text, bloc, tier, domain, event type, and primary industry tag. It also explicitly differentiates itself from get_event by positioning search_events as the discovery/shortlisting tool.

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 gives an explicit decision rule: 'Use to discover or shortlist events; for a single event's complete record, use get_event.' This names the sibling alternative and states the condition for choosing one over the other.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden, and it does so thoroughly: it reveals that lookups are precomputed, explains mode-specific behaviors, discloses that homogeneous_only is ignored on adjacency modes and echoed in ignored_params, describes bare-node-id resolution, and notes how existing-but-edge-less nodes are reported.

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

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

The description is dense but every sentence earns its place, and the most important decision-relevant information is front-loaded. The mode-by-mode behavior, alternative tool, parameter interactions, and edge-case handling are organized logically with no filler.

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

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

Given the tool's complexity, the description is remarkably complete: it specifies what each mode returns, which parameters affect which modes, what happens to ignored parameters, how IDs are normalized, and how edge-less nodes are classified. Even without an output schema or annotations, an agent has enough context to invoke this tool 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?

Although the schema already covers each parameter, the description adds meaningful cross-parameter semantics: cc_types and max_depth apply to both path and adjacency modes, homogeneous_only is path-only, and bare numeric IDs are resolved with the canonical form echoed as resolved_node_id. This goes well beyond the schema's per-property 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?

The description opens with a specific verb-resource pair, 'Walk the Coordination Topology lineage graph', and immediately grounds it in the parent→child Coordination Connection DAG. It distinguishes itself from sibling tool get_topology by explicitly separating traversal walks from structural metrics and whole-graph summaries.

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 states when to use this tool versus get_topology: 'For a node's structural metrics or the whole-graph summary rather than walks, use get_topology.' It also maps each mode to its intended use and clarifies which parameters apply to which modes, giving an agent clear selection criteria.

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