Warmth Engine Observatory

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses tier-based differences (free vs full), the nature and source of `energy_context`, and explicitly states 'Descriptive — recorded status, never inference.' This goes well beyond a basic read tool.

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

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

The description is longer than average but well-structured: purpose first, then usage, filtering, tier details, and data provenance. Every sentence adds value, though the `energy_context` explanation is somewhat verbose. It remains readable and front-loaded.

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

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

There is no output schema, so the description must cover return values. It does so by listing the actor fields, explaining free vs full tier differences, detailing `energy_context` provenance, and clarifying the descriptive nature. This is complete for a retrieval 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?

The input schema already provides complete descriptions for both parameters (actor_name and designation), and the description only repeats the filtering capability without adding new semantics. Schema coverage is 100%, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Retrieve whole Sovereign Capability Profile (SCP) actors' and lists the included fields. It also distinguishes itself from `query_scp` by explicitly naming the alternative for different use cases, making the purpose 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 when-to-use guidance: 'Use to fetch complete actor records' and contrasts with `query_scp` for pivoting/comparisons. It also mentions filtering options, providing clear context for when this tool is appropriate.

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 of behavioral disclosure. It states the tool serves the complete register ('Served whole and free'), is purely descriptive ('never inference'), and details what is included. This adds value beyond the tool name, though it omits potential error behaviors or edge cases.

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 without being verbose. Each sentence earns its place: the first lists contents, the second states availability and nature, the third clarifies no inference and points to the methodology tool. Front-loaded and 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?

Given the tool has no parameters and no output schema, the description provides a thorough overview of what the tool returns (the full register with all attributes, metadata, and provenance) and its limitations ('never inference'). It also links to a sibling for related definitions, making it self-sufficient for an agent to understand the tool's scope.

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; the input schema is empty. Per guidelines, the baseline for 0 params is 4. The description does not need to explain parameters, and none are missing. It adds contextual meaning about the returned data instead.

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 the WEO Bloc Membership Register, enumerating specific contents (nations, bloc assignments, membership categories, evidence, source URLs, metadata, provenance). It uses a specific verb 'Retrieve' and resource, and distinguishes itself from get_methodology by noting that category definitions are served separately.

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 provides clear context for when to use this tool (to get the full register) and explicitly points to get_methodology for category definitions, acting as an alternative. It does not explicitly state when not to use it, but the reference to the sibling tool offers useful 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?

No annotations are provided, so the description carries the full burden. It goes well beyond a simple 'retrieve' by disclosing key behavioral traits: link types have distinct semantics, the full tier adds fields, and links are never flattened to a yes/no qualifies flag. It does not mention pagination or rate limits, but for a read-only retrieval tool the verb and description are adequately 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 adds value, from the core purpose to the semantic distinctions and the pointer to the sibling tool. It is a single long paragraph with semicolons, which is acceptable given the amount of necessary detail, though it could be slightly better structured with bullet points for link_type variants.

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

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

There is no output schema, so the description must explain the return semantics. It does so thoroughly by naming the link fields and their meanings, explaining tier-dependent additions, and clarifying how to derive sole-vs-multiple basis. It lacks explicit mention of response pagination or ordering, but the tool's conceptual complexity is well covered.

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 all three parameters at 100% coverage. The description adds contextual meaning beyond the schema, such as example actor values ('US', 'CN', 'GB') and the crucial note that GB is used rather than UK, plus the meaning of filter results in terms of link types. This enhances usability without repeating schema content.

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 event↔dimension membership links' which clearly identifies the tool's purpose. It also distinguishes itself from the sibling tool get_capability_signatures by explicitly directing higher-order uses there, and the domain terms (SCP, actor, dimension) are well-defined.

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 provides explicit filter guidance, including a practical note that GB is used instead of UK, and explains when to prefer a sibling tool: 'For the higher-order signatures built from these links, use get_capability_signatures.' It also clarifies how to derive sole-vs-multiple basis from the links, which tells users how to use the output for analysis.

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 transparency burden. It discloses that results are precomputed, directional, span multiple dimensions, include metadata and non-signature same-capability clusters, and are 'served whole and free.' It also describes behavioral traits such as omitting signature_id to get the whole set and passing it for one. This is rich contextual information beyond any 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?

Although lengthy, each sentence adds essential information: definition, content of returned data, parameter behavior, and relation to sibling tools. The structure is logical and front-loaded with the core purpose, followed by usage details. No filler or 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?

For a tool with one optional parameter, no output schema, and no annotations, this description is exceptionally complete. It explains what is returned (nodes, directional legs, dimension span, attribution, narrative, metadata, non-signature clusters), the semantic caveat (corroborating texture), and how to retrieve subsets. An agent can confidently select and invoke 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%: the property description already explains that signature_id is an example 'CS-001' and omitting it returns all signatures. The tool description adds no substantive new parameter detail, just repeats the omit/pass behavior. Baseline 3 is appropriate when the schema already documents the parameter fully.

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 Capability Signatures, specifying they are directional CC chains/hubs spanning multiple SCP dimensions. It distinguishes from sibling get_capability_links by explicitly directing users there for underlying event↔dimension membership links, so there is no ambiguity about what this tool returns.

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 guidance on when to use this tool ('corroborating structural texture rather than a headline finding') and when to use an alternative ('For the underlying event↔dimension membership links, use get_capability_links'). It also explains how to request the whole set vs. a single signature, covering invocation context.

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 explaining behavior. It discloses that the return payload varies conditionally: full evidence on the full tier or when an endpoint is a sample event, and base fields only otherwise. This is genuinely useful behavioral context beyond the basic read operation, though the terms 'full tier' and 'sample event' remain unspecified.

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

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

Two sentences, tightly packed: purpose and example, then usage guidance, then return behavior. No filler or redundancy. Every phrase contributes meaning, and the most critical information is front-loaded.

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

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

For a single-parameter retrieval tool with no output schema, this description is nearly complete: it states what it does, when to use it, how to identify the target, and what to expect in the response. The only gap is the undefined domain-specific terms ('full tier', 'sample event'), which the agent may need to infer from other tool 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?

Schema description coverage is 100% with the property docstring already explaining the identifier format. The description reinforces the parameter's purpose but does not add new semantic information beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb ('Retrieve') and a clear resource ('a single Coordination Connection (CC)'), identified by a concrete example ('CC-06-11-3'). It differentiates from the sibling tool get_connections by stating the scope is a single CC when the exact identifier is known, making the purpose 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?

Provides explicit when-to-use guidance: 'Use when you have the exact identifier.' It also names the alternative for listing/filtering: 'to list or filter CCs, use get_connections.' This is a textbook example of usage guidelines with a clear alternative.

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 takes on the transparency burden. It discloses the read-only nature through 'Retrieve' and details the return structure (id, source/target event IDs, type name + number, confidence, direction, and additional evidence fields for certain endpoints). However, it does not mention potential side effects, pagination, or error behavior, though these are less critical for a retrieval tool.

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

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

The description is two sentences: the first front-loads the primary purpose and filters, the second adds sibling differentiation and output details. Every sentence earns its place without redundancy or fluff.

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

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

The tool has 3 optional parameters and no output schema, so the description compensates by summarizing the return fields and explaining the difference between full and partial tiers. This covers the main usage context. Minor gaps like pagination or max results are not required for a simple filtered listing, making it adequately complete.

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

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

The input schema already provides 100% coverage with descriptions for all parameters. The description reiterates these filters (event as source/target, type 1–7, confidence CC-V/CC-E/CC-A) but adds little new meaning beyond clarifying the event filter's bidirectional scope, which the schema already states. Thus it meets the baseline without significant added value.

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 Coordination Connections (CCs), specifying they are typed, directional relationships between events. It distinguishes itself from the sibling get_connection_by_id by explicitly directing users to that tool for fetching a single CC.

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 provides explicit guidance: use this tool to list CCs with optional filters (event, type, confidence), and use get_connection_by_id for a single CC. This gives a clear when-to-use and when-not-to-use alternative.

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 burden of behavioral disclosure. It reveals matching behavior (exact-first then substring), fallback behavior for unknown terms (returns sample terms), return value details, the optional-term status mode, and tier availability ('Served in full on both tiers'). This is 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?

The description is six sentences, each earning its place. It front-loads the core purpose, then provides return details, usage modes, sibling distinction, matching behavior, and availability without redundancy or verbose 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 tool with one optional parameter and no output schema or annotations, the description is fully complete: it covers what it does, when to use it, what it returns, matching rules, fallback behavior, status mode, and tier support. It leaves no significant gaps for an agent to infer.

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 the single parameter's description at 100%, the tool description adds substantial extra meaning: it gives examples, explains the omit-for-status behavior, details matching semantics, and describes what an unknown term yields. This goes far beyond the schema's basic property 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 opens with 'Look up WEO Contribution Architecture vocabulary', specifying a clear verb and resource. It provides concrete example terms and lists specific return values (context, section anchor, deep link). It explicitly contrasts with get_methodology, distinguishing it from siblings.

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 'Use to resolve participation vocabulary' and clarifies that the Methodology Manual (`get_methodology`) governs what qualifies, providing direct guidance on when to use this tool versus the alternative. It also explains when to omit the parameter 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 full burden. It discloses that figures are computed live and always reflect the present database, plus the limitation that the secondary-industry breakdown is full-tier only. This adds meaningful behavioral context beyond the schema, though it does not describe the response structure or any potential performance implications.

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 sentences, front-loaded with the main purpose, then efficiently lists all statistic dimensions and adds key behavioral notes. Every sentence earns its place, with no redundancy or 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 having no output schema and no annotations, the description provides a comprehensive list of the statistics returned, notes live computation, and highlights a limitation. For a zero-parameter tool, this is highly complete and leaves little ambiguity about what the agent can expect.

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, and the description explicitly states 'No parameters' and explains that figures are computed live, making it clear no input is needed. According to the rubric, a zero-parameter tool with explanatory context merits a baseline 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 description clearly states the tool retrieves current corpus statistics and enumerates the specific metrics (events, Coordination Connections, Sovereign Capability Profile actors, ENT stats, etc.). It is distinct from sibling tools like get_actors or get_metrics by focusing on aggregate coverage stats.

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 implicitly indicates when to use this tool: to get a live overview of the entire corpus. It does not explicitly name alternatives or exclusions, but the scope is clear, and the 'no parameters' note reduces ambiguity. Lacks explicit 'when not to use' guidance, hence not 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the zero-padded ID requirement and tier-dependent return behavior: free tier returns complete records for sample events but only classification facts for others, while full tier returns every field. This is valuable context beyond a simple 'get by ID'. However, it does not mention error handling (e.g., not found) or any rate limits, so slightly less than 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 compact yet information-dense. The purpose is front-loaded in the first clause, followed by usage guidance, parameter format, and tier behavior. Every sentence delivers distinct value with no redundancy. The use of semicolons and commas keeps it readable despite multiple clauses.

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 the essential context: what the tool does, when to use it, how to format the only parameter, and what to expect from different tiers. It also implies that the return value includes various record fields. Given there is no output schema, this is reasonably complete. It does not mention possible errors or pagination, but those are minor omissions for a simple ID-based fetch 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?

The input schema already provides a description for `event_id` with the same zero-padded examples ('"06", "141"'). The tool description repeats this exactly without adding new meaning. Since schema description coverage is 100%, the baseline is 3, and the description adds no additional parameter semantics beyond what the schema already states.

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 clear verb and resource: 'Retrieve one event by ID', followed by a comprehensive list of what the event record contains (classification, assessment, sources, industry tags, ENTs, bloc analysis, tier rationale). It also distinguishes itself from the sibling `search_events` by explicitly stating its use case: use when you already hold an event ID. This fully satisfies purpose clarity.

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

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

Explicit guidance is provided: 'Use when you already hold an event ID; to find IDs, use `search_events`.' This gives a clear decision rule and names the alternative tool. Additionally, tier-based usage differences (free vs full) are stated, helping the agent know what to expect. No exclusions are necessary given the simple use 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?

No annotations are provided, so the description carries full burden. It discloses that the three arrays are never merged, each has distinct claim types, and the free tier does not leak paid fields. This goes beyond basic behavior and gives critical context about gating and derived view 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 long but densely informative, with clear use of backticks for field names and logical structure. Each sentence adds value, though it could be tightened by trimming some redundant phrasing like 'in one call' and 'separate arrays, never merged' which are repeated conceptually.

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 high complexity (three distinct arrays with detailed fields) and no output schema, the description fully enumerates the return structure and semantics. It also addresses gating and provides alternative tool references, making it complete for an agent to select and invoke.

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% for the single parameter, so the baseline is 3. The description only repeats 'Pass event_id' without adding new meaning beyond the schema's example and focal event 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 uses specific verbs and resource: 'Assemble the stack journey for one event' and details the three returned arrays (coordination, material, capability). It clearly distinguishes from siblings by naming alternative tools for different scopes (get_threads, traverse_coordination).

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

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

Explicitly states when to use this tool versus alternatives: 'For the material layer alone, use `get_threads`; for the directed multi-hop coordination lineage between events, use `traverse_coordination`.' Also gives a direct instruction to pass event_id.

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 burden of behavioral disclosure. It discloses the matching strategy (exact-first, then substring) and the behavior for unknown terms (returns a sample of available terms). It also lists the return components (definition, section anchor, deep link, version), providing a transparent view of what to expect.

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 three sentences, well-organized and front-loaded with the primary purpose. Each sentence adds distinct information: what it does, what it returns, and how to use it. No fluff 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?

For a single-parameter lookup tool with no output schema, the description is sufficiently complete. It explains inputs, matching behavior, unknown-term handling, and the output components, making it self-contained. The simplicity of the tool does not demand additional details like pagination or rate limits.

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% (the only parameter 'term' is described with examples). The description adds extra value by explaining the matching behavior (exact-first, substring) and the fallback for unknown terms, which goes beyond the schema's static description and helps the agent understand how the parameter is processed.

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 a specific verb ('look up') and resource ('WEO methodology definition'), and it explicitly distinguishes itself from sibling tools by focusing on methodology vocabulary rather than actors, blocs, events, or network queries. The examples of terms ('CC-V', 'T2', 'PAA') reinforce its unique purpose.

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 provides a clear when-to-use directive: 'Use to resolve any vocabulary the other tools return.' It does not explicitly list exclusions or alternatives, but the instruction to use it for unfamiliar terms is sufficient for guiding an agent in most scenarios.

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 full burden. It discloses that returns are dated observations, never live recomputations; explains status flags (published, pre_operational, insufficient_corpus); states comparability only within a taxonomy epoch; and notes pre-operational corpus limitations. Minor omission: does not describe return format (e.g., JSON structure) but lists returned metrics.

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 well-structured, starting with purpose, then usage differentiation, parameter guidance, and behavioral caveats. Every sentence adds value. Somewhat long but justified by complexity; could be slightly more concise but remains effective.

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

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

Given the tool's 2 parameters, no output schema, and absence of annotations, the description thoroughly covers purpose, sibling differentiation, parameter semantics, behavioral traits, and constraints. It is complete 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% with descriptions for both parameters. The description adds value by clarifying 'Omit metric for all of them' and 'set include_history for the full append-only series', enhancing understanding beyond the schema's 'default false' and enumerated list.

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 WEO quantitative coordination metrics, lists the specific metrics (CSTF, transmission matrix, FFD, CBCF, CGR), and distinguishes itself from the sibling tool get_coverage_stats by explaining the difference between derived, dated observations and live corpus counts.

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 tells when to use this tool (for dated metrics) vs. get_coverage_stats (for live counts). It also provides parameter guidance: omit 'metric' for all metrics, set 'include_history' for full series. It explains status values and comparability constraints, making invocation 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?

With no annotations provided, the description carries full burden and does so admirably. It discloses that threads lack connection type and confidence grade ('either the asset match is verified or it isn't'), explains outbound vs. inbound linking, enumerates linkType values, and mentions that each link carries a sourced claim and host-event field. It also 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 moderately long but every sentence contributes essential context: defining threads, contrasting with connections, explaining link types, directional behavior, and pointing to an alternative. It is front-loaded with the core definition and uses clear, structured punctuation.

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 adequately covers the return structure by detailing the link contents (linkType, asset, host-event field) and the two invocation modes. It also covers the conceptual model, sourcing, and pricing. The only omission is error conditions, but that is not critical for a retrieval tool with a simple optional parameter.

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% (event_id has a description), so baseline is 3. The description adds meaningful usage semantics: passing event_id returns both directions with specific examples ('182' deployer, '196' producer), while omitting returns the whole layer. This goes beyond the schema's brief description and clarifies the parameter's effect.

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 'Infrastructure Threads' — a distinct factual material-link layer for named AI hardware assets. It uses a specific verb ('Retrieve') and resource ('Infrastructure Threads'), and explicitly distinguishes this from Coordination Connections and points to get_event_stack as a different tool for value-chain stacks.

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 provides explicit usage instructions: pass event_id for that event's linked events (with directionality explained), omit event_id for the whole layer. It also tells when NOT to use it: 'For one event's value-chain stack, use get_event_stack' and clarifies that threads are not Coordination Connections, implying get_connections or similar for connection-type queries.

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 full burden. It discloses that the topology is precomputed, describes the DAG structure, lists the specific metrics returned for both modes, and mentions the full tier's additional analyst layer. While it doesn't discuss edge cases or side effects, it's a read operation and the level of detail is strong.

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 efficiently structured: purpose first, then two usage modes, then alternatives, then filters, then tier details. Every sentence adds distinct value, and the text is well-organized despite being information-dense.

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 fully covers what the tool returns (explicit lists of metrics for both whole-graph and node modes), clarifies when to use alternatives, and explains filters. It is complete for a read-only topology retrieval tool with moderate 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%, so baseline is 3. The description adds meaning beyond the schema by explaining the two modes (omit node_id vs pass node_id) and describing what each mode returns (whole-graph stats vs node metrics), plus clarifying that filters return matching nodes. This is more than just restating parameter names.

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 the precomputed Coordination Topology, a structural lineage layer over a DAG. It distinguishes between whole-graph statistics and node-specific metrics, and explicitly differentiates from sibling tools (traverse_coordination, get_event_stack).

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 guidance: use this for topology metrics, use traverse_coordination for actual paths, and get_event_stack for value-chain stacks. It also explains when to omit node_id (whole-graph) vs pass it (node metrics) and mentions optional filters.

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 does so well. It discloses that readouts are descriptive, never causal inference, and details the free/full tier field differences including evidence, sources, and escalation_trigger. It also explains the behavior of omitting parameters, providing a complete behavioral picture.

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 is logically structured: purpose, distinct from sibling, modes, output characteristics, tiers, and edge-case hint. It is dense with useful information without redundancy or fluff.

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 having no output schema, the description is remarkably complete. It explains what each mode returns, the fields included (met, headline, evidence, sources, escalation_trigger), the difference between tiers, and the behavior when no parameters are provided. This gives an agent enough context 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?

While schema coverage is 100%, the description adds substantial meaning beyond the schema. It explains the semantic role of each parameter (e.g., `dimension` pivots one dimension across actors, `actors` lays actors side by side, `watch` returns the dimension_watch register) and clarifies the combinatorics (choose exactly one mode). This greatly enhances 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 explicitly states the tool queries the SCP register by pivoting and comparing, with specific modes like `dimension` and `actors`. It distinguishes itself from the sibling `get_actors` by noting that `energy_context` is not returned here. This is a clear, specific verb+resource definition with sibling differentiation.

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 provides explicit when-to-use guidance, differentiating from `get_actors` and describing each mode (dimension, actors, watch) with examples. It also states that omitting all parameters yields a usage hint, and identifies the free vs. full tier differences. This is thorough and actionable.

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 discloses important behavioral aspects: the result cap by limit (default 20, max 50) and the tier-based access restrictions that affect which fields are returned. This goes beyond the schema and provides critical context about response variability, though it does not fully detail all edge cases or side effects.

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 concise and well-structured. It front-loads the core purpose, then adds usage guidance and tier-specific behavior. Every sentence provides meaningful information without redundancy or fluff.

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 having no output schema, the description explains what is returned (matching events with metadata) and clarifies the differences between free and full tier responses. It also covers the limit behavior and explicitly points to get_event for complete records. This makes the tool's behavior clear enough for an agent to use it correctly in various contexts.

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 documents all parameters with 100% coverage, so the description does not need to explain each parameter. The description confirms the limit cap and lists the filter categories, but these are already present in the schema. It adds minimal new meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool searches and filters the WEO event corpus by keyword or classification, listing specific filter dimensions. It explicitly distinguishes itself from get_event, which retrieves a single event's complete record, making the purpose unambiguous and distinct from siblings.

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 ('to discover or shortlist events') and provides a direct alternative for a different need ('for a single event's complete record, use get_event'). This gives the agent clear decision guidance for tool selection.

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, but the description fully discloses behavioral traits: precomputed lookups over a DAG, mode-specific return behavior, how cc_types and max_depth bound walks, path-only homogeneous_only being echoed in ignored_params for adjacency modes, node_id resolution from bare numbers, and reporting nodes that exist but have no backbone edges. This goes beyond basic read-only metadata and explains edge cases.

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

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

The description is a single dense paragraph, but every sentence earns its place: mode definitions, sibling distinction, parameter interactions, and edge cases. It is front-loaded with the core purpose and mode list, then parameter behavior, then resolution behavior. No redundant or filler content.

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 7 parameters, 4 modes, no annotations, and no output schema, the description covers all essential aspects: what each mode returns, how parameters behave across modes, ignored params, and input normalization. The absence of an output schema is compensated by describing return semantics in the mode definitions.

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 adds substantial cross-mode semantics: cc_types and max_depth apply to path and adjacency walks, max_depth means path length vs hop count depending on mode, homogeneous_only is path-only and echoed in ignored_params otherwise, and node_id resolution behavior. This adds meaning far beyond the schema's 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?

Clearly states the tool walks the Coordination Topology lineage graph and enumerates each mode's output (path returns paths with CC-type sequences, ancestors/descendants return reachable nodes, neighbours returns direct parents/children). Distinguishes from sibling get_topology by noting it is for structural metrics/summary rather than walks.

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 tells the agent to use get_topology when wanting structural metrics or whole-graph summary instead of walks. Also specifies when each mode is appropriate (path for paths between source/target, ancestors/descendants for hierarchy traversal, neighbours for direct connections). Describes parameter interactions and ignored params.

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