ComOS Federation

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds valuable behavioral context: it 'performs no transaction,' returns knowledge in a specific voice, and details the return type (markdown). This contradicts nothing in the annotations and enriches the agent's understanding of side effects and 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?

The description is concise (4 sentences) and front-loads the core purpose. Every sentence adds value: what it does, read-only nature, return type, and an example call. No fluff 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 of this complexity (no params, no output schema), the description is complete: it states purpose, side effects, return format, and usage example. The annotations cover safety, and the description covers everything an agent needs 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?

With zero parameters, the schema is trivial, but the description explicitly states 'Zero-arg' and provides an example with {}. This removes any ambiguity about the input contract, fully covering parameter semantics. The schema coverage is effectively 100% by virtue of having no parameters.

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 function: 'Read About ComOS — the Federation User Manual's knowledge' with a specific verb and resource. It further specifies the return format ('composed about-us knowledge as markdown') and explicitly notes it's read-only. This effectively differentiates it from the many sibling tools that perform mutations or queries.

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 when to use this tool—whenever the About ComOS knowledge is needed—and clarifies it's zero-arg and identity-free. It provides a concrete example call. However, it does not explicitly mention alternatives or when not to use it, though the tool's simplicity lessens the need for extensive exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context beyond annotations: the score is 'a trust-weighted function of real settled transactions, not raw volume' and 'a fact surfaced, not a verdict rendered.' It also details return shapes for different argument modes, aiding correct interpretation.

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 fairly long but well-structured: a leading concept, usage instructions, a pairing note, and a detailed 'Returns:' section. Each sentence contributes value, and the example call is concise. Slightly dense but not bloated, earning a 4.

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

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

With no output schema, the description fully documents return structures for both invocation modes. It explains filtering, ranking semantics, and safety nuances. The reference to catalog tools provides sibling context. Complete for a moderate-complexity read-only leaderboard tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning by tying parameters to usage modes and showing distinct return shapes for 'tenant_id=' vs 'Default/platform/limit'. While the schema already covers each parameter, the natural-language summary and example enhance understanding, justifying 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 description clearly states the tool is a live arena ranking agent-run businesses by settlement-signed reputation. It explicitly differentiates from sibling catalog tools: 'the catalog is how you enter; the arena is how you're ranked.' This makes the purpose specific and distinct.

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 patterns: 'Omit args for the top of the board; platform= to filter by vendor type; tenant_id= for one business's rank.' It also contrasts with the catalog tools by noting the arena is for rankings, providing a clear when-to-use versus alternatives.

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

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

The description is rich in behavioral detail: decay lifts within ~30s, no review/operator is needed, identity comes from the token, and the return value is the refreshed liveness standing. However, these state-changing self-heal effects directly contradict the annotation `readOnlyHint: true`, so the behavioral profile is unreliable and scores 1 due to annotation contradiction.

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 carries distinct, load-bearing information: purpose, implicit attestation, self-heal trigger, operator-freeze exception, identity handling, return value, and invocation example. There is no filler or repetition of schema 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?

Despite zero parameters and no output schema, the description fully equips the agent: it explains what the tool does, when to use it, when not to use it, side effects, delay, identity source, return value, and example invocation. The only significant concern is the annotation contradiction already scored under behavioral transparency.

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 is empty, but the description adds the necessary invocation guidance by giving the example `call federation_attest with arguments {}` and noting that identity is read from the token rather than from parameters. This tells the agent exactly how to invoke the tool correctly.

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 clear verb and object: 'Attest your manager root is alive' and anchors it to the CO 264 liveness mandate. It also distinguishes this tool from freeze/unfreeze/suspend siblings by scoping it to liveness attestation and self-healing only.

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 gives explicit when-to-use guidance: call when idle, or when self-healing a mandate-decayed root. It also gives a clear when-not-to-use situation by stating that an explicit operator freeze is NOT lifted by attesting, and notes that regular privileged activity already counts as implicit attestation.

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

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

Annotations already cover read-only, idempotent, non-destructive. The description adds value by disclosing per-mode output shapes (groups/platforms/summary vs agents vs full card with repo), and notes that deprecated platforms return an empty list ('honest-empty'). This is useful behavioral detail beyond the structured annotations.

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

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

Front-loaded with purpose and usage, tight sentences, no fluff. Each clause carries information. It's a bit dense with the output-shape specifications, but those replace the missing output schema, so they're justified. Slight over-verbosity in the output format listing but acceptable.

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 compensates by enumerating the return shapes for each call mode (no args, serves/platform filter, agent slug). It also provides a concrete example call. Given the tool's 3-parameter surface, zero required params, and no output schema, the description is remarkably complete.

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

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

Schema covers all three parameters well (100% coverage), so the baseline is 3. The description adds meaningful framing: it maps each parameter to its output modeholand explains omission semantics ('Omit for the whole fleet') and the filter interplay with serves/platform. It also contrasts agents vs platforms conceptually, deepening parameter understanding. That pushes it to 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 description states a specific verb+resource+scope: 'Browse the ComOS network's autonomous agent fleet — what each agent does and who it serves.' It explicitly lists the beneficiary taxonomy (merchant/shopper/platform/manager) and names its sibling companion (federation_catalog_platforms) with a crisp conceptual contrast ('agents are the operators you hire; platforms are what you become'), so it clearly differentiates from related catalog 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 explains when to use which invocation mode: 'Omit args for the fleet grouped by who-it-serves and by platform; pass serves= or platform= to filter; agent=<slug> for one agent's full card.' It also names the alternative (federation_catalog_platforms) and states the distinction, which is ideal usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is known. The description adds non-obvious behavioral details: presets are included in results but never count in summary.total (CO 455), and the same call works recursively at any depth. This goes beyond annotations and adds valuable context, though it doesn't discuss rate limits or edge cases, which are less critical given the read-only 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?

The description is long but every sentence carries substance. It is front-loaded with the core purpose, then systematically covers sides, presets, parent navigation, and the sibling relationship. It also includes a concise example call and return format. While it could be trimmed slightly (e.g., the CO 455 reference may be unnecessary), the organization and density are strong for a tool with this complexity.

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 only 2 optional parameters, the tool's behavior is complex: recursive catalog, side filtering, presets, and interactions with sibling tools. The description adequately explains all these aspects, including explicit return structure ({ platforms: [...], summary: { total, side, parent } }), the exclusion of presets from totals, and the usage context. It provides a complete picture for an agent to use and interpret results correctly, and no output schema is needed because the description fills that gap.

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

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

Schema coverage is 100%, so a baseline of 3 is appropriate. The description enriches both parameters: it clarifies side='vendor' returns sell-on platforms (retail, bookings) and side='customer' returns run-tools (messaging, shipping), and gives concrete examples for parent (e.g., parent='messaging' returns email/sms/dm). It also implicitly explains the interaction (when parent is present, side is ignored, as noted in the schema). This adds meaningful usage context 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 verb+resource: 'Browse the ComOS network's composable platforms as a recursive catalog.' It distinguishes from siblings by explicitly contrasting with federation_catalog_agents: 'platforms are what you become; agents are the operators you hire to run them.' Clear differentiation and precise scope.

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: it explains two modes (side for sell-on vs customer), how to navigate via parent, and notes that presets are not platforms. It also names the sibling tool and clarifies when to use each ('Pairs with federation_catalog_agents: platforms are what you become; agents are the operators you hire to run them.'). This gives clear context for choosing this tool over alternatives.

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

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

Annotations already cover read-only, idempotent, non-destructive. The description adds valuable context: 'Public read — auth_token is optional', describes grouping behavior (collapses variants, price range, options), and details the return structure. No contradictions.

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 paragraph but well-structured: purpose, usage preference, tenant source, read state, return format, and example. Every sentence adds value, though it could be slightly more concise; still appropriately sized for a tool with no output 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?

There is no output schema, so the description carries the full burden of explaining returns. It fully describes the return structure, per-tenant data, and provides an example call. It also covers all required and optional parameters, making it complete for an agent to select and invoke 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 parameter descriptions, so baseline is 3. The description adds value by explaining tenant_ids come from federation_list_tenants, and clarifies the 'limit' parameter's role in grouping (max variants fetched before grouping). This goes beyond 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?

Clearly states it searches product families across multiple tenants, explicitly distinguishing from sibling federation_catalog_search_multi which returns exact variant SKUs. The verb 'search' and resource 'product families' are specific.

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 says 'Prefer this for discovery' and instructs to use federation_catalog_search_multi when exact variant SKUs are needed. Also notes tenant_ids come from federation_list_tenants or 'all', providing clear when-to-use 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?

Beyond the readOnly and idempotent hints, the description discloses that it is a public read with optional auth_token, and that it operates in parallel across tenants. It also outlines the return structure, adding meaningful behavioral context.

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

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

The description is information-dense but well-organized, starting with purpose, then usage, alternatives, source, auth, return format, and an example. It is slightly verbose but each sentence contributes value, so it remains appropriate in length.

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 fully explains the return format (results with tenant_id, status, data, error; summary with totals) and provides example arguments. It covers purpose, usage, and output, making it complete for a read-only search tool without an output schema.

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

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

While the schema already covers parameter descriptions, the description adds context by noting that tenant_ids can be 'all' or come from federation_list_tenants, and provides an example call. This enhances understanding 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 clearly states that the tool searches products across multiple tenants in parallel, returning flat results (one row per variant). It also distinguishes itself from the grouped variant, which aids in 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?

Explicitly instructs to use federation_catalog_search_grouped_multi for browse/discovery flows, providing a clear alternative. Also mentions that tenant_ids come from federation_list_tenants, giving actionable guidance on obtaining required inputs.

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

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

Annotations declare read-only, idempotent, non-destructive. The description adds that it's a cheap operation, returns an opaque hash and a specific structure, and is for change detection. No contradiction with annotations. It provides context beyond the annotations, like the meaning of the return value and its purpose.

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 but thorough. It covers purpose, usage, return format, and example in a single paragraph. Each sentence serves a function, with no redundancy. Slightly long but still efficient, so a 4 is appropriate.

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 tool with one parameter, the description is comprehensive. It explains the purpose, usage scenario, return structure, and provides an example. It also gives a warning about stale references. Given the simplicity and existing annotations, this is 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 schema already fully describes the single parameter (tenant_id) with a clear description. The description reinforces it with an example call, but doesn't add new semantic meaning beyond what's in the schema. Baseline of 3 is appropriate for high schema coverage with no extra insight.

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: returning a fingerprint of the catalog for a tenant for change detection. It distinguishes itself from catalog search by framing it as a cheap check and referencing catalog_search results, so the agent understands this is not the same as retrieving catalog content.

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

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

The description explains when to use it (before acting on product IDs) and what to do if the version differs (re-run catalog_search). It provides explicit guidance on the workflow and mentions the alternative catalog_search, making it clear 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?

Annotations already mark this as readOnly, idempotent, and non-destructive. The description adds substantial behavioral detail: constraints eliminate non-qualifying tenants, organic_rank is fact-only, promotion is a separate disclosed label that never influences rank, and an eliminated block shows dropped tenants and the clauses that dropped them. No contradiction with annotations.

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

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

The description is front-loaded with a strong first sentence and uses useful formatting, but it suffers from redundancy: the return payload is described twice in nearly identical terms. The closing example 'call federation_choice_compare with arguments {}' provides no useful guidance and adds noise.

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

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

With no output schema, the description appropriately explains return behavior: qualifying candidates, aligned facts, fact-only organic_rank, promotion slot, and eliminated block. It also covers candidate scoping and constraint semantics. Minor gaps remain around how `limit` interacts with ranking and the exact shape of 'aligned facts', but overall it is complete enough for a 4-parameter tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value beyond the schema by giving concrete constraint examples (dimension/op/value), explaining the candidates alternatives in detail, and clarifying that constraints eliminate candidates. It does not discuss `limit`, but the schema already covers that.

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+goal: 'Compare federation tenants on their structured choice_profiles to pick one for a need.' It clearly distinguishes this from catalog/search siblings by framing it as a pre-purchase comparison step and emphasizing the separate, disclosed promotion slot vs. fact-only organic rank.

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 when to use it: 'Use this to choose a tenant before buying via the catalog/order path.' It also explains the two candidate-scoping modes (tenant_ids after catalog search vs. discover by need). It does not explicitly name sibling alternatives to avoid, but the usage context is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value by specifying the exact return envelope: the choice_profile, freshness timestamp, and a separate disclosed promotion label (null if not promoted). This helps the agent anticipate output format and null behavior. No contradiction with annotations.

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

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

The description is relatively short but contains redundant return information (the first sentence already lists the return items, and the 'Returns:' sentence repeats them nearly verbatim). The example is inaccurate and unnecessary. While not bloated, not every sentence earns its place, and the poor example hurts clarity.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers purpose and return values well. However, the contradictory example and redundant return description introduce potential for misuse, preventing it from being fully complete. The core information is present, but the flaw lowers it below an ideal 4.

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 provides 100% coverage with a clear description for tenant_id, so baseline is 3. However, the description's example says 'call federation_choice_get with arguments {}' which directly contradicts the required tenant_id. This misleading example could cause the agent to omit the mandatory parameter, and the description adds no useful semantic beyond the schema. The presence of incorrect guidance warrants a score lower than baseline.

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

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

The description uses the specific verb 'Fetch' with a clear resource ('one tenant's full choice_profile'), details the contents (organic comparable facts, per-vertical attributes), and distinguishes itself from the sibling tool federation_choice_compare by referencing that compare narrows to a single tenant. This unambiguously states what the tool 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?

Explicitly instructs to use after federation_choice_compare has narrowed to a single tenant, giving a concrete when-to-use context. It doesn't list exclusions or alternatives beyond federation_choice_compare, but the guidance is sufficiently clear for an AI agent.

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?

Adds substantial behavior beyond annotations: mcp-session-id persistence, 24h idle expiry, re-entering re-scopes, the authoritative progressive tool surface, and how info tenants behave. Annotations already declare safe/idempotent behavior, and this description enriches them without contradiction.

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

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

Purpose is front-loaded and the content is mostly high-value, but it is verbose and repeats 'authoritative' in the return-value summary. Still, the detailed session, REST, and response information earns most of its length.

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

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

With no output schema, the description fully compensates by explaining the reply structure (platform_tools, platform_tool_defs, composed_tool_defs), session lifecycle, tool listing behavior, and REST twin. This 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?

The schema already covers tenant_id at 100%, with a description and example placeholder. The tool description adds the JSON call shape and examples of tenant-specific platforms, but does not deeply increase parameter-level meaning 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?

Description opens with a specific verb+resource: 'Enter a tenant to receive its tool surface (progressive disclosure).' It clearly distinguishes itself from siblings by naming the prerequisite federation_list_tenants and by explaining that entering scopes the session to the tenant's real action and knowledge 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?

Provides clear context: list tenants first, then enter, re-enter to resume, and shows a REST twin alternative. It lacks explicit when-not-to-use exclusions, but the workflow and alternatives are clear enough to guide the agent.

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?

The description reinforces the read-only nature and adds a note about not disclosing private manager standing, which goes beyond the annotations. However, much of the phrasing mirrors the annotations (readOnlyHint, idempotentHint) and adds limited new behavioral insight.

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 extremely repetitive and verbose. Phrases like 'Read-only — reflects the live governance constants so what you read is what enforces' and 'discloses no specific manager's private standing' are stated twice, and the return description lists many terms without adding clarity. This could be condensed significantly.

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 outlines the structure of the returned governance model object but lacks a concrete example or deeper detail about the values and their implications. Given the absence of an output schema, the description is moderately complete but not fully self-contained.

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 no parameters in the schema, so there is nothing to explain. The description appropriately omits any parameter details, making this dimension fully satisfied.

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: to expose how the federation governs its agents, detailing the autonomy ladder and related concepts. However, the wording is verbose and could be more succinct.

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 no guidance on when to use this tool versus the many other federation_* sibling tools. It lacks any context about scenarios where this governance introspection would be preferred or necessary.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint, providing a safe read operation baseline. The description adds useful behavioral context by listing the specific content areas covered (quick-start, tenant_id, cart session persistence, product IDs, authentication, common workflows) and states it returns Markdown help text. No contradictions.

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, front-loaded with the core purpose and 'CALL THIS FIRST'. It includes the return type and an example, with no wasted words.

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

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

For a simple help tool with zero parameters and strong annotations, the description is complete. It explains what the tool returns, what topics it covers, and how to call it, sufficient for an agent to invoke 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 tool has zero parameters, so the schema coverage is trivially 100%. The description notes 'call federation_help with arguments {}' which confirms the empty input. With 0 params, baseline is 4 as no parameter explanation is needed.

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 'Get usage instructions for the MCP federation' with a specific verb and resource. It distinguishes itself from sibling tools by being the help/instruction entry point, explicitly positioned as 'CALL THIS FIRST'.

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 guidance: 'CALL THIS FIRST to understand how to use tools correctly'. It provides context on when to invoke this tool, but does not explicitly mention alternatives or exclusions, which is slightly less than the highest bar.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds meaningful behavioral context: required OAuth scope 'journal:read', tenant ownership restriction, return order oldest→newest, and limit behavior. It also explains the intended use case in a cold session, which annotations cannot convey.

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

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

The description is four sentences and front-loaded with the core purpose. It packs in usage context, permissions, return behavior, and an example efficiently. The only slightly extra element is the cryptic 'CO 230-001' reference, but it does not detract significantly.

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

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

For a read-only replay tool with 2 well-documented parameters and no output schema, this description sufficiently covers when to call, prerequisites, ordering, and result shape. There is no significant missing context that would prevent correct invocation.

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

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

Schema coverage is 100% with descriptions for both tenant_id and limit, so the baseline is 3. The description adds value by emphasizing 'with only your tenant id', noting the return respects the limit, and providing a concrete invocation example. This goes slightly beyond the schema without being redundant.

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 'Replay your agent journal oldest→newest', using a specific verb and resource along with ordering semantics. It also distinguishes itself from its sibling federation_journal_append by explicitly pairing with it as the write counterpart.

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 gives explicit when-to-use guidance: 'Call this at the start of a cold session — with only your tenant id — to reconstruct your intent and resume where you left off.' It also clarifies scope limitations (own tenants) and permission requirements, making the invocation context 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?

Beyond the readOnlyHint and destructiveHint annotations, the description adds specific behavioral guarantees: never returns a challenge or secret, includes the attestation chain head, and points to the full chain URL. This is valuable context that annotations do not cover. No contradiction.

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-organized and front-loaded, but it repeats 'Never returns any challenge or secret' twice, adding slight redundancy. Otherwise, every sentence serves a purpose and the structure is logical.

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

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

For a read-only tool with one optional parameter and no output schema, the description fully specifies return fields, usage semantics, security guarantees, and a related well-known resource. It provides an example and covers all necessary context for correct invocation.

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

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

The schema already describes manager_id as 'defaults to the caller.' The description reinforces this with 'Omit manager_id to read your own' and adds an example with empty arguments. With 100% schema coverage, the description adds minimal new semantic detail, 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 reads a manager root's bound public key and lists the specific fields (public_key, alg, kid, bound_at). It also distinguishes itself from sibling tools like federation_key_bind (which binds keys) and federation_key_challenge (which likely involves secrets) by emphasizing read-only and never returning a challenge or secret.

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 context: a counterparty verifies signatures, and you can omit manager_id to read your own key. It also hints at alternative resources (full attestation chain at well-known URL). However, it does not explicitly name alternative tools or state when not to use it, though the 'never returns any challenge or secret' clue differentiates it from key_challenge.

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?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful context: that the values are 'measured', 'never asserted', and computed 'live from the gateway's own audit records (CO 292)'. It also discloses the empty-history behavior honestly. This is a model example of annotation-plus-description synergy.

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?

Though dense, the description front-loads the core concept and then efficiently covers usage, empty history, and a motivational catchphrase. The repetition of the empty-history return value is a small blemish—'an empty history' is explained twice—but the structure is otherwise tight and motivating.

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 2-param, no-output-schema tool, the description thoroughly covers the main use case, the data source, the meaning of an empty result, and an example call. It could mention whether the output is a single object or array, but since there's no output schema, the `{ p50, p95, p99, sample_count }` shape is sufficient. The example `call federation_latency with arguments {}` is trivially helpful but not harmful.

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 description only needs to add semantics beyond the schema. The description explains that tool= filters by tool name and limit= widens/narrows the sample window, offering the non-obvious default (500) and cap (5000) hint implicitly through 'default 500, cap 5000' in the schema. The description's added value is the 'sample window' framing, which maps the params to the underlying intent. Slight deduction for redundancy with schema details.

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 leads with a specific verb+resource combination ('Reproducible latency — the MEASURED p50/p95/p99...computed live from the gateway's own audit records') and clearly distinguishes this from asserting/estimating latency. It's unmistakably about querying measured latency percentiles of tool executions, which differentiates it from any assert-based sibling 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 explicit usage context: 'Omit args for whole surface; tool= to scope to one tool; limit= to widen/narrow the sample window.' It also covers the empty-history case and says to 're-call after traffic.' It doesn't name alternative sibling tools, but for a latency-measurement tool this is a clear contextual signal, though not an exhaustive exclusion list.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the return format and example call, which is useful but doesn't go beyond what annotations provide in terms of behavioral traits like pagination or performance.

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, front-loaded with the main purpose, and includes a clear return type and example. Every sentence adds value without 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?

Given the tool's simplicity (no parameters, no output schema), the description is complete. It explains the return structure and provides an example. It could mention if there are any limitations (e.g., only shows active tenants), but for a list tool, this is adequate.

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 schema coverage is 100% (empty properties). The description correctly notes the example call with empty arguments, which is sufficient. Since there are no parameters to explain, the description adds value by confirming no arguments are needed.

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 lists all available tenants in the federation and specifies the returned data (tenant IDs, names, status). It distinguishes itself from sibling tools like federation_list_agents and federation_list_managers by focusing on tenants.

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 use this tool to discover which tenants you can interact with, providing clear context for when to use it. It doesn't explicitly mention alternatives or when not to use it, but the purpose is clear enough given the sibling tool names.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, but the description adds meaningful context beyond those: it reinforces 'public and read-only,' explicitly states 'no token needed,' and details the exact return structure (offer and how_to_apply). It also clarifies the optional channel parameter is telemetry-only. The description complements annotations without contradicting them, fully disclosing behavior.

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

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

The description is somewhat verbose with metaphorical language (e.g., 'door's window,' 'door') but remains informative. It covers purpose, usage, return format, and an example in a compact 3-4 sentence structure. While not perfectly concise, it front-loads the key facts and each sentence contributes value.

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

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

The description is complete for this simple tool. It has only one optional parameter, no output schema, and the description fully explains the return format, the application steps, and the read-only nature. It also includes an example invocation. No gaps remain that would confuse an agent.

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

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

There is one optional parameter 'channel' with a schema description ('Optional: where you found us...'). The description adds context by explicitly stating 'Arrival telemetry only — the offer content never varies by channel,' which clarifies that the parameter has no effect on output. Given schema coverage is 100% and the description provides additional reassurance about its non-impact, this is slightly above baseline.

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

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

The description clearly states the tool's purpose: 'Read the ComOS network's vendor offer — public and read-only, no token needed.' It distinguishes from the sibling tool federation_apply by explicitly framing this as 'the door's window' and federation_apply as 'the door,' clarifying the read/apply split. The verb 'read' and resource 'vendor offer' 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?

The description explicitly provides usage context: it states the tool is public and read-only, requires no token, and then gives exact steps to apply (obtain OAuth token, call federation_apply). It also explicitly says 'This tool changes nothing; it is the door's window, and federation_apply is the door,' clearly indicating when to use this vs. the sibling tool. This is excellent 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?

The description confirms the operation is read-only and cost-free ('free to read', 'Reads ... never priced') and states that the returned prices are authoritative ('the price you read is the price applied'). However, it contains odd phrases like 'CO 287' and 'Robots are effective-forward' (likely a typo for 'Reprices'), which add confusion rather than clarify behavior. The readOnlyHint annotation already covers the primary trait, and the description adds some but not extensive clarity.

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 extremely verbose and repetitious, using many words to convey simple facts about pricing. It contains awkward phrasing, a run-on structure, and apparent typos (e.g., 'CO 287', 'the same map the metering seam enforces'). This obscures the key information and significantly reduces clarity and readability.

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 attempts to explain the return structure in a loose form (e.g., 'Returns: { title, ... }') and provides pricing policy context. However, it lacks a formal output schema, and the verbose, error-laden text makes it difficult to extract the exact return format. It covers the main points but would benefit from a clearer, more structured explanation.

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 has zero parameters, so there is nothing for the description to explain. The description mentions 'call federation_pricesheet with arguments {}' which aligns with the empty schema, but it adds no semantic value for parameters. Per the rubric, a high schema coverage (100% here) yields a baseline of 3.

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 that this tool provides the federation pricesheet, listing per-act Com prices for each platform. It distinguishes itself from sibling tools by focusing on pricing information, and it explicitly notes that it is a read operation ('free to read'). Minor ambiguities like 'CO 287' do not obscure the core 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 does not explicitly state when to use this tool versus alternatives. It provides pricing policy details (e.g., 'Any tool not listed is free') but does not guide the agent on when to fetch prices, such as before invoking a paid tool. No comparison with sibling tools is given, so the usage context is only implicitly derived.

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

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

Annotations already provide readOnly, idempotent, and non-destructive signals. The description adds meaningful behavioral context beyond annotations: it is deterministic ('the same intent always routes the same way'), non-transactional, and returns an explicit empty route with 'unroutable: true' instead of a silent default. It does not mention auth or rate limits, but those are not critical for this 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 front-loaded with purpose, includes realistic examples, and clearly separates routing behavior from transaction behavior. Some redundancy exists between the prose and the 'Returns:' section, and the erroneous final example keeps it from a perfect score.

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

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

The description compensates for the lack of an output schema by listing the returned fields (platform_id, label, why_matched, score, entry_points) and the empty-route case. It covers when to call, what to do next, and deterministic behavior. The invalid example is the main gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds helpful examples of free-text intent values and explains that the result includes entry_points for next steps. However, the closing example 'call federation_search with arguments {}' conflicts with the required 'intent' parameter and adds no meaningful limit semantics.

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

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

The description uses a specific verb ('Route'), identifies the resource ('natural-language intent'), and names the output ('ranked platform(s)'). It clearly distinguishes itself from siblings by positioning this as the entry-point router: 'the first thing to call'.

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 call this first and explains the next step: 'you then act on that platform with the chosen tenant.' It also clarifies what the tool does not do ('This returns a ROUTE, not a transaction'). It does not explicitly name alternatives or exclusions, but the intended usage context is clear.

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

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

Beyond the annotations (readOnly, idempotent), the description adds crucial behavioral details: it is public, read-only, always free, computed from real GL rows, never asserted, and notes that unbalanced entries are a defect even when margin is positive. This significantly enhances transparency about side effects 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 thorough but somewhat repetitive (e.g., 'public, read-only, always free' and 'same verify, don't trust posture'). It includes an example call and all necessary field definitions. While not overly verbose, the content could be slightly tightened without loss of information.

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

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

The description fully explains the tool's domain: the meaning of each returned field (reserve, outstanding, margin, unbalancedEntries), the solvent condition requiring both conditions, the computation source (real GL rows), and the example output. Even without an output schema, the description provides complete context for the return values.

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 has zero parameters (empty properties), so schema coverage is 100% and there is nothing to describe. The baseline for 0 parameters is 4, and the description correctly omits parameter details since none exist.

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's purpose: it returns the live solvency invariant for a federation's dollar-backed currency, detailing the reserve, outstanding, margin, and unbalanced entries. It clearly identifies the resource (dollar ledger) and action (returns invariant), and distinguishes itself from sibling tools focused on latency or pricesheet.

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 when to use the tool (to check solvency or backing existence) and clarifies it is computed from real GL rows, never asserted. It does not explicitly contrast with alternatives, but the sibling context makes the use case clear. The 'verify, don't trust' posture and 'checking whether backing exists is discovery' provide implicit guidance.

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

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

Annotations already mark readOnlyHint=true and destructiveHint=false, so the description does not need to restate safety. It adds value by disclosing the exact return contract: a tuple-like result with 'tenant' possibly null and 'found' boolean. This explains not-found behavior and the absence of an output schema, going beyond the annotation signals.

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

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

The description is compact and front-loaded: it states the purpose first, then the return shape, then a concrete example. Every sentence contributes useful information and there is 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?

This is a simple read-only tool with one parameter and no output schema. The description covers the purpose, expected inputs, return format, and null case. It also provides an executable example. Given the low complexity and strong annotations, no additional context is needed.

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

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

Schema coverage is 100% and the single parameter is described adequately ('The tenant ID to get information for'). The description adds a usage example, but this is largely a re-statement of the schema. No additional semantic detail is provided beyond what the schema already gives.

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 'Get detailed information about a specific tenant', which clearly identifies the verb (get), the resource (tenant), and the scope (specific tenant). It also lists specific fields ('metadata, description, and configuration') and returns a structured result, distinguishing it from sibling tools like federation_list_tenants or federation_delete_tenant.

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 makes the context clear: use this when you need detailed information for a specific tenant. It does not explicitly name alternatives or exclusion criteria, but the purpose is distinct enough from the sibling tools that the usage context is 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond by detailing the return object's fields and the door-state caveat (tokened apply vs tokenless never admits), adding valuable behavioral context without contradicting annotations.

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

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

The description is slightly verbose but well-structured: it opens with purpose, contrasts with sibling, gives usage guidance, details the return object, and includes a caveat and example. Each sentence earns its place, though it could be tightened.

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 no params and no output schema, the description comprehensively covers the return value's structure, the caveat, and pointers to related resources, making it complete for the agent's needs.

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

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

There are zero parameters, so the baseline is 4. The description doesn't need to explain params and doesn't, but it includes an example call with empty arguments, which is helpful.

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: 'Why build on ComOS — the case for becoming a vendor, not just a buyer.' It distinguishes itself from federation_help by explicitly contrasting 'HOW' vs 'WHY'.

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: 'Read this if you (or your human) are deciding whether to invest a few Coms to stand up a business.' Also points to the alternative: 'federation_help tells you HOW; this tells you WHY.'

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds value beyond that by explicitly stating 'performs no transaction,' specifying the return format ('composed walkthrough knowledge as markdown'), and noting identity-free behavior. This is helpful context for the agent.

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

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

Four short sentences, each serving a purpose: purpose, behavioral guarantee, return format, and invocation example. No filler or redundancy. The structure is front-loaded and scannable.

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 zero-arg, read-only tool with no output schema, the description is fully complete: it states the resource, the behavior, the return type, and gives an example. There are no missing critical details that the agent would need.

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

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

There are zero parameters, so the schema already fully covers parameter semantics (vacuously). The description reinforces this with 'Zero-arg' and an example call with {}. This meets the baseline for zero-parameter tools.

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 clear verb ('Read') plus a specific resource ('How to use ComOS — the operational walkthrough's knowledge'), and adds a distinctive voice qualifier ('comos-federation voice'). This differentiates it from sibling tools like about_us_about or federation_help by targeting a specific knowledge artifact.

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

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

It clearly implies the context of use: when the agent needs the operational walkthrough knowledge. It mentions zero-arg and identity-free, which sets expectations for invocation. However, it doesn't explicitly name alternatives or exclusion cases, so it stops short of full guideline clarity.

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?

Despite readOnlyHint and idempotentHint annotations, description adds crucial behavioral context: the 'uncited(out_of_scope)' return for invalid ids, versioning details, and that v1 only supports 'current' string.

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

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

Four sentences, information-dense, perfectly front-loaded with the core action, then covers edge cases and versioning without 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?

Complete for a version-limited comparison tool with good annotations - explains current state, limitations, and future plans. Note: tools introspecting themselves by the same name ('introspection_corpus_compare') suggests this is an introspective consistency test.

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 0% (no descriptions in schema), but the description fully compensates by explaining the only valid value ('current') and how both sides work, plus example call.

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?

Clear verb 'Compare' + resource 'corpora' + scope 'by id' with specific example.

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 ('pass it for both sides to sanity-check'), alternatives ('any other id returns uncited(out_of_scope)'), and future version context ('v1.1 will surface prior pins').

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so no contradiction exists. The description adds the scoping effect of the `repo` parameter (restricts to intra-repo) and discloses the cross-repo limitation, which enriches the annotation-only picture without repeating it. It doesn't describe pagination, empty-result behavior, or the structure of returned disagreement points.

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 fits in about 70 words across four sentences, with a clear lead sentence. However, 'Highly load-bearing for honest epistemic surfacing' is rhetorical flourish that adds little operational meaning, and the malformed example wastes space and misleads. Front-loading is good; the tail could be tightened.

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 'Returns: The detected points of corpus disagreement' line provides minimal but real return-value info. The description covers repo semantics and a limitation, but omits topic semantics, edge cases (no disagreements, empty corpus), and return structure. For a 2-parameter tool this is passable but not thorough.

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 0%, so the description must carry parameter explanations. It explains `repo` ('restricts to intra-repo disagreement') but leaves the required `topic` unmentioned beyond its name. Worse, the example says 'call ... with arguments {}' — an empty object — while `topic` is required, making the example actively misleading about how to invoke the tool.

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 'Ask the corpus where its artifacts disagree on a topic' is specific about the verb (ask/probe), resource (corpus artifacts), and outcome (disagreement discovery). It invokes a distinct concept from sibling tools like introspection_corpus_query (general query) and introspection_corpus_probe_scope, though it doesn't explicitly name those alternatives.

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 'highly load-bearing for honest epistemic surfacing' phrase suggests when it adds value, and the Phase 3.5 note plus 'cross-repo disagreement is a future tool' disclose a limitation. However, there's no explicit when-not-to-use guidance or named sibling alternatives (query, probe_scope) to steer selection — it leaves usage context implied rather than stated.

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

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

Annotations already mark this as read-only/non-destructive. The description adds useful behavioral details: the out_of_scope return and the optional repo scoping. No contradiction with annotations exists.

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 short and front-loaded, but the 'Returns: The scope of the requested corpus region' sentence is redundant with the earlier output statement. The example 'with arguments {}' is misleading because the schema requires a 'topic' argument.

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

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

For a simple read-only two-parameter tool, the description covers the main return modes and optional scoping. It lacks explicit interaction with sibling introspection tools, but the basic invocation context is 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?

With 0% schema description coverage, the description must compensate, and it only partially does: it explains 'repo' as scoping to one repo and implies 'topic' is the subject of the probe. It does not clarify topic format, required behavior, or relationship between the two parameters beyond that.

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 action ('Ask the corpus what it covers') and resource ('corpus') and clarifies the output ('topical map with citations' or 'out_of_scope'). It does not explicitly name sibling tools, but the scope/coverage framing distinguishes it from query/generate/probe_disagreement.

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

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

It clearly implies when to use: to determine corpus coverage on a topic. It also explains the optional repo scoping behavior. However, it gives no explicit exclusions or comparison to alternative introspection tools.

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

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

Beyond the read-only annotation, the description adds behavioral details such as the cited/uncited return kinds, the verification of content_excerpt as a substring, and the pinned manifest resolution. These details enhance transparency about the tool's operation.

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, covering the action, return type, key details, and optional parameter in a compact manner. It avoids unnecessary repetition, though it includes some technical jargon that could be simplified.

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?

While it explains the return format and a parameter, it lacks context on error cases, usage scenarios, or limitations. The reference to 'Phase 3.5' is cryptic and may not be fully understandable to an agent without additional context.

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 description explicitly explains the 'repo' parameter as filtering candidate manifest entries. The 'question' parameter is implied by the tool's purpose, though not explicitly named. This adds meaningful context beyond the raw schema.

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

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

The description clearly states the tool's purpose: 'Ask the corpus a question' and describes the return format. It distinguishes itself from sibling tools by focusing on querying the corpus, which is 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?

The description does not explicitly state when to use this tool over alternatives. It mentions 'Phase 3.5' but does not clarify the context or provide comparisons to other tools. The intended usage is implied but not clearly demarcated.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, and the description adds that drift is reported but never silently reconciled—clarifying a key behavioral boundary. This goes beyond annotation, though it doesn't discuss auth or rate limits.

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?

Description is detailed but not bloated; it front-loads the core purpose and packs node/edge/drift reporting into a single sentence. The example call is a minor extra, but overall 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?

No output schema exists, yet the description fully specifies the two possible return shapes (change graph vs. no-evidence) and the structural elements (nodes, edges, drift). Covers behavior, scope, and examples relevant for a zero-parameter read-only 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?

Tool has zero parameters command schema is empty, so the baseline is 4. The description adds nothing about parameters (none exist), but it does explain the return shape, which is useful.

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 clearly states the tool returns the dependency graph of change orders across all registered ComOS repos, specifying node/edge types. This is distinct from sibling tools like introspection_system_diff or introspection_system_list_nodes, making its purpose 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?

No explicit guidance on when to use this tool versus alternatives. It provides an example call but lacks any 'use when' or 'prefer this over X' context, leaving selection to the agent's inference.

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

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

Annotations already mark readOnly/idempotent/non-destructive, and the description adds substantial behavior: traversal over edges, provenance data (which CO reached it, edge source, note), response kinds ({kind: 'evidenced', value, chain} or {kind: 'no_evidence_available'}), and parameter defaults. This goes well beyond what annotations provide, with no contradiction.

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 mostly tightly structured and front-loaded with the core purpose, but it has redundancy: the final 'Returns: The set of surfaces a change reaches.' repeats the earlier response-shape sentence, and the example 'call introspection_system_change_reach with arguments {}' is empty and unhelpful. Every sentence does not fully earn 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 the tool's complexity (graph traversal, provenance, evidence chain, parameter defaults, and no output schema), the description covers all necessary input semantics, defaults, output shapes, and behavioral details. It is complete enough for an agent to invoke correctly, with only minor undefined jargon (CO, D8) that is acceptable in context.

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 0%, so the description fully compensates by explaining each parameter: origin_slug is the CO directory slug with an example, max_hops bounds traversal depth (default 1), and include_parent_child toggles decomposition tree reach (default true). This gives meaning beyond the raw schema.

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

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

The description uses a specific verb 'Return' with a clear resource 'REACH of a change' and defines scope: 'every artifact across every registered repo' traversed over the change-graph's interest + parent/child edges. This distinguishes it from sibling tools like change_graph (which likely returns the graph) and list_nodes (which lists nodes), 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?

It provides clear context on what the tool computes (the reach of a change, surfaces affected) and explains key parameters and defaults (max_hops, include_parent_child). However, it does not explicitly name alternatives or state when-not-to-use it, which would be needed for 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?

The description discloses extensive behavior beyond annotations: it details the exact return structure (two possible kinds with fields), the default window and snapshot cap, the effect of passing a different repo, and the no_evidence_available case. This is far more than the readOnlyHint/idempotentHint annotations provide, so it fully satisfies transparency.

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 informative but slightly verbose. It leads with purpose, then details data fields, defaults, parameters, and return types. However, the final 'Returns: The climb history for the requested node.' is redundant given the earlier return structure explanation. It is well-structured but could be tightened without loss.

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

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

The tool is moderately complex with multiple return cases and no output schema. The description covers all essential aspects: data contents, default behavior, parameter semantics, success and failure return shapes. It is complete enough for an agent to invoke it correctly without additional external knowledge.

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 0%, so the description must explain parameters. It does so clearly: since is an ISO timestamp, limit is an integer ≤1000, repo is a string with a default and subtree semantics. It also explains defaults for window and max snapshots, linking parameters to their effects. This fully compensates for the lack of schema 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 clearly states it is a time-series read of honesty-ratio snapshots, returning the climb trajectory over a window. It lists specific data fields (chain_length, honesty_ratio_percent, NN-state counts) and distinguishes itself from sibling introspection tools (e.g., change_graph, probe) by focusing on historical snapshots rather than changes or probes.

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: it is for reading climb history with defaults for window and repo. However, it does not explicitly state when to prefer this over alternatives like introspection_system_probe or confidence, though the purpose itself implies usage. No exclusions or when-not-to-use guidance is given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe read-only nature is covered. The description adds that it returns a 'no_evidence_available' kind when no evidence exists, and mentions the return structure, but does not disclose details like whether results are paginated or if there are rate limits. Since annotations cover the safety profile, the description adds moderate value, warranting a 3.

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 detailed but dense, covering purpose, modes, return types, and an example in a few sentences. It front-loads the core query capability and then provides mode-specific details. The inclusion of 'Added by CO 2026-05-30-022-003' is minor extra noise, but overall it's structured and efficient, earning a 4.

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 moderate complexity (three modes, two optional parameters, no output schema), the description is fairly complete: it explains each mode, the return format, and provides an example. It does not mention edge cases like whether co_id is required for touched_co or if agent_id is required for agent_autonomous, but the schema shows they are optional, so some ambiguity remains. Still, it covers most needed context, warranting a 4.

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 0%, so the description must compensate for parameter meanings. It does so by explaining the 'mode' parameter with three enumerated values and their semantics, plus indicating that 'co_id' and 'agent_id' are used with specific modes. The example call further clarifies usage, which is more than the schema alone provides, justifying 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 description clearly states the tool queries the 'CO-management decision log' with a specific verb ('Query') and resource, and distinguishes between three modes with concrete examples (touched_co, agent_autonomous, escalated). It also provides the return format, making its purpose unambiguous and distinct from siblings like introspection_system_change_graph.

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 for when to use each mode, including what each mode returns (e.g., 'what decisions touched a CO', 'what is escalated and waiting on the operator'). It implicitly suggests that using mode is required and that co_id or agent_id are needed for certain modes, but does not explicitly state when not to use this tool versus alternatives, so a 4 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?

Annotations already indicate read-only, idempotent, non-destructive. The description adds the response types ('evidenced' vs 'no_evidence_available') and the evidence chain concept, which slightly extends beyond annotations. No contradiction with annotations.

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

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

The description is concise, front-loaded with the core purpose, and includes an example call. It is well-structured and easy to parse, with all key information in a few sentences.

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

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

Given the tool's complexity (enum, optional param, response variants) and lack of output schema, the description is fairly complete. It explains the response shapes and references a companion tool for valid node ids. It could mention more about when to use this over introspection_system_probe or introspection_system_list_nodes, but the core context is present.

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?

Description clarifies node_kind enum values (artifact, tool, tenant) and node_id semantics (path, name, id), plus the optional repo scope. This adds meaning beyond the schema's property types. However, the description doesn't fully compensate for the 0% schema documentation, as it leaves some ambiguity about evidence chains and when repo is needed.

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 returns a confidence number for a federation node with an evidence chain. It distinguishes itself from other introspection tools by specifying the operation (returning confidence) and the resource (federation node). It also provides the response format and an example.

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 context for when to use the tool: to get a confidence score for a node. It also mentions that valid node ids come from introspection_system_list_nodes, which is useful. However, it does not explicitly state when not to use it or contrast with alternative introspection tools.

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

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

The annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds transparency by specifying the two possible return shapes (evidenced or no_evidence_available), but does not mention potential errors or side effects beyond what annotations cover.

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, consisting of two sentences and an example. It is well-structured, with the purpose first, followed by parameter notes and return types. No unnecessary words.

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

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

The description explains the return structure, including both possible variants and their fields. It provides an example invocation. However, it does not elaborate on what Gap[] entails or the meaning of 'chain', and it does not specify error scenarios. Given the output schema is absent, this is reasonably 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 description explains the required parameter scope_kind and its values, and clarifies that scope_id is required when scope_kind='tenant'. However, it does not mention the optional repo parameter, leaving its semantics ambiguous. The example only shows scope_kind, not the full parameter set.

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: to enumerate structural coverage gaps, specifically listing examples of gap types (silent tools, artifacts with no eval, un-probed tenants). It distinguishes itself from other introspection tools by focusing on coverage gaps.

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

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

The description does not explicitly state when to use this tool versus alternatives like introspection_system_diff or introspection_system_list_nodes. It provides a clear purpose and an example invocation, but lacks direct guidance on 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about baseline comparison and return semantics, but it does not describe important behavioral details such as what happens with invalid baselines, how 'structural difference' is represented, or whether large diffs are truncated. No contradiction with annotations exists.

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 short and front-loaded with the core purpose, and most sentences carry useful information. However, the final 'Example: call introspection_system_diff with arguments {}' is not a real example and is misleading because the tool requires four non-empty arguments. That sentence wastes the only illustrative slot and introduces confusion.

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 four required parameters, zero output schema, and no return-shape details. The description covers parameter meanings and states that the return is 'the structural difference between the two states,' but it does not explain what that structure looks like, what baseline_edge cases exist, or how to interpret the result. It is adequate for a simple diff-like tool but leaves gaps for an agent invoking it autonomously.

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

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

With schema description coverage at 0%, the description carries the parameter-semantics burden, and it largely succeeds: it explains node_kind/node_id by referencing 'confidence,' fixes baseline_kind to 'since,' gives the baseline_iso_date format, and lists the source of valid node ids. This adds real meaning beyond the bare schema, though the 'same as confidence' reference is indirect and relies on sibling-tool knowledge.

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 action and resource: 'Compare a node's evidence against a baseline date.' It further clarifies the domain by pointing to 'introspection_system_list_nodes' for valid node ids and by naming the expected result as 'the structural difference between the two states.' It does not explicitly contrast with sibling tools, but the verb+resource is specific enough to distinguish it from most 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 gives practical guidance by saying node_kind/node_id are 'same as confidence' and that valid ids come from introspection_system_list_nodes. It implies when the tool is appropriate—comparing a node against a baseline—but does not explicitly state when to use it instead of related introspection tools or mention exclusions.

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?

The readOnlyHint, idempotentHint, and destructiveHint annotations already signal it as a safe read operation; the description adds substantial behavior beyond that: response variants, activation states, optional repo scoping, and what happens when there is no evidence. It does not contradict any annotations.

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

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

The early sentences are dense and helpful, but it ends with a vague, duplicative 'Returns: The set of structure-graph nodes' after already giving a precise return shape. The change-order provenance sentence is also marginal; it does not helps an operating agent.

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 optional parameter with no output-based schema, the description covers result shape, enum state values, conditional return kinds, and plausible semantic behavior. It falls short of complete because 'chain' and activation-state meanings are left unresolved and no error details are given, but the tool is still usable from this description.

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 gives only the bare repo string field with no description, so the description compensates by saying 'Optional repo scopes the artifact list to one repo (Phase A)'. That is enough for the only parameter, though it does not define the expected repo format or explicitly state the omitted behavior.

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 explicit action and target: 'Enumerate every artifact, tool, and tenant the federation knows about', with a specific purpose of rendering picker UIs. It also lays out per-node fields and return shapes that separate this tool from sibling tools like introspection_system_list_repos or federation_list_tenants.

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

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

It clearly states the intended context — 'needed to render picker UIs' — and explains when the optional repo parameter changes scope. It does not include explicit exclusion or when-not-to-use guidance or compare itself to alternative tools, but the usage context is readily understandable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds useful behavioral context: it returns a specific payload shape, includes only active federation registry repos, and explains the downstream use case, going beyond what annotations convey.

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

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

The description is functional but not tight: the 'Returns:' line partially repeats the return shape already described, the 'Added by change-order...' line is unnecessary for an agent, and the example adds little for a zero-parameter tool. It could be trimmed to two sentences without loss of meaning.

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

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

Despite having no output schema, the description fully specifies the return format ({kind, value, chain}) and the items in the repos array. It also clarifies the registry membership condition (active in federation registry), which is complete enough for an agent to invoke and interpret results.

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

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

The tool has zero parameters and the schema coverage is 100%, so the schema imposes no burden. The description gives the call an empty arguments example and explains the tool's output purpose, which aligns with the baseline of 4 for zero-parameter tools.

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 action ('List') and the specific resource ('ComOS repositories that contribute to introspection'), with a concrete purpose. It distinguishes itself from the many sibling tools by explicitly framing itself as a discovery step for introspection_system_climb_history.

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 directs when to use this tool: 'Use this to discover which repo ids to pass to introspection_system_climb_history.' This provides actionable guidance and a clear relationship to a companion tool, which satisfies the when/where guidance requirement.

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

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

Annotations already declare the tool as read-only (readOnlyHint=true) and non-destructive (destructiveHint=false), so the description doesn't need to restate that. It adds that the response carries 'node-specific evidence rather than a collapsed number' and that valid node ids come from another tool. However, it doesn't describe the structure of the evidence trace or any error behavior, missing an opportunity to enrich beyond what annotations provide.

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

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

The description is somewhat verbose with an unhelpful example ('call introspection_system_probe with arguments {}') that implies no required parameters, contradicting the schema. The phrase 'Returns: The probe result for the requested target' is redundant and adds little. Could be tightened to focus on the evidence trace and required parameters.

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 schemabool, the description should clarify what the 'evidence trace' looks like or at least mention that it differs from a scalar confidence value. It references introspection_system_list_nodes for valid ids, which is helpful, but lacks details on node_kind values, error conditions, and the overall behavior for different node types. The misleading example further reduces completeness.

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 0% (description only references 'repo' and the argument shape relative to 'confidence'). The required parameters node_kind and node_id are not described beyond the example call, which is incorrect (empty {} ). The mention of 'repo' being optional adds some value, but the enum values for node_kind are left to the schema without explanation.

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 ('Return the full evidence trace') with a clear resource ('a single federation node'). It hints at differentiation from the 'collapsed number' tool (likely confidence) but does not explicitly name or contrast with the sibling introspection_system_confidence. The reference to 'same argument shape as confidence' provides context but could be clearer about the distinguishing 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?

Provides some usage guidance: mentions that valid node ids come from introspection_system_list_nodes Light, and that `repo` optionally scopes to a single repo. However, it does not explicitly state when to use this tool over alternatives (like confidence or list_nodes), nor does it mention the requirement for node_kind and node_id as mandatory parameters beyond the example with empty arguments, which is misleading.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds useful behavioral context beyond that: the operation is public, non-gating, and returns raw markdown rather than a structured summary. No contradiction with annotations.

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

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

The description is front-loaded with the core action and resource, and is relatively tight. The metaphor about reading the pricesheet and the example call add value but make it slightly longer 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 single-parameter, read-only tool with strong annotations and schema coverage, the description fully covers the purpose, accepted values, return format, and safety profile. There are no significant gaps.

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 covers 100% of parameters with a complete enum and per-value descriptions. The description repeats the enum and gives a generic call example, but adds little beyond the schema's own parameter documentation. Baseline 3 is appropriate.

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

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

The description states the tool fetches a ComOS legal instrument as raw markdown and explicitly enumerates the four document types (terms, privacy, dpa, retention). This clearly distinguishes it from the sibling tools, none of which are legal-instrument readers.

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: read these legal terms 'the way you read the pricesheet', and notes the tool is public, read-only, and discloses rather than gates access. It does not explicitly list when-not-to-use or alternative tools, but the read-only framing and the exclusive legal-instrument scope make appropriate usage clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false; the description adds context by stating 'no claim required' and explaining the return shape. It also clarifies the three read modes, providing useful behavioral detail beyond the annotations.

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

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

The description is well-structured with a clear definition, target explanations, return format, and example. It is a bit long but each sentence adds value; the example could be improved to show a valid call with the required target.

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

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

For a read tool with 6 parameters and three modes, the description thoroughly covers usage scenarios, return structure, and references to the external field guide. It compensates well for the lack of an output schema and provides sufficient context for an agent 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?

While schema descriptions cover all parameters (100%), the description adds conditional meanings: it maps target to required parameters (post_id for comments, submolt for submolt), which is not explicit in the schema. However, the example with empty arguments is slightly misleading given the required target parameter.

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 reads Moltbook, a specific social network for AI agents, and differentiates among three targets (feed, submolt, comments). It distinguishes from siblings like moltbook_post (write) and federation_* tools by emphasizing the external context and read-only nature.

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 advises using it to 'listen before you contribute' and explains which parameter to pass for each target, but does not explicitly state when not to use it or alternative tools. The guidance is implicit and contextually clear, though it lacks explicit exclusions.

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