ComOS Federation Gateway

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

Although annotations already declare readOnlyHint/idempotentHint/destructiveHint, the description adds meaningful behavioral context beyond the structured data: it performs no transaction, returns composed knowledge as markdown, is identity-free, and notes the specific voice. 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 compact and front-loaded. The first sentence states the main purpose, followed by short, informative sentences covering safety (read-only), return format, and an invocation example. 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 zero-parameter, no-output-schema knowledge tool with strong annotations, the description fully covers what's needed: resource, voice, side-effect profile, return type, identity behavior, and a call example. There is no meaningful 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?

With zero parameters, the baseline is 4, and the description reinforces this with 'Zero-arg; identity-free' plus the explicit example 'call about_us_about with arguments {}.' There is nothing more to add for a zero-arg 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 description uses specific language: 'Read About ComOS — the Federation User Manual's knowledge (in the comos-federation voice).' It clearly names the verb (Read), the resource (About ComOS/Federation User Manual knowledge), and the return (markdown). It helps distinguish itself from siblings like how_to_about and federation_why by scoping the exact voice and nature of the knowledge.

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: read-only, performs no transaction, zero-argument, identity-free, and includes a usage example. It does not explicitly name alternatives or give when-not-to-use guidance, but for a static knowledge-read tool, the context is sufficient.

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 destructiveHint=true and readOnlyHint=false, and the description goes well beyond: it states authorization is per-inner-tool (scope, fail-closed tenant ownership, pricing apply unchanged), that it adds reach but never authority, and enumerates typed refusals. It also discloses that the inner tool's result is returned verbatim.

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

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

Front-loads the core purpose, then branches into mode-specific rules, authorization guarantees, and refusals. Dense but every clause carries decision-relevant information; slightly lengthy for a single description but no obvious filler.

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

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

Given a mutation tool with no output schema, the description covers invocation modes, parameter routing, authorization semantics, failure modes, and return behavior (inner result verbatim). An agent has everything needed to call it correctly under either client configuration.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful usage context beyond the schema: which mode requires tenant_id and which omits it, and how the 'tool' argument's namespace depends on the chosen path (platform_tool_defs vs federation_help with tool_defs), plus the 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?

States a specific verb (invoke) and resource (any served tool through the root surface), with a clear audience qualifier (list-gated clients, CO 525/529). Distinguishes the two invocation modes (branched vs unlisted root) and names the sibling tools that provide the names/schemas (federation_enter_tenant, federation_help).

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

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

Explicit routing rules: pass tenant_id + tool + arguments for branched platform tools; omit tenant_id for unlisted root tools. Where to obtain names/schemas is named for each path, and typed refusals (tenant_id_required, tenant_id_not_applicable) encode the when-not conditions.

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/idempotent/destructive annotations, the description discloses that scores derive from counters only the settlement path can write, that the evidence trail is a public hash-chained log verifiable without credentials, and that amounts are never emitted. These are concrete behavioral facts not present in the annotations. Nothing in the text contradicts 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 front-loaded with purpose and usage, but it carries esoteric internal cross-references (CO 200, CO 571, CO 472) and rhetorical framing ('a fact surfaced, not a verdict rendered') that an agent cannot act on without external context. It is informative but could be tightened without losing meaning.

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

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

With no output schema, the description supplies complete return shapes for both the leaderboard and single-tenant modes, defines what `evidence` is, and covers the read-only safety profile. Paired with parameter routing and sibling guidance, everything an agent needs to invoke and interpret the tool 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by mapping each parameter to an outcome (omit for the whole board, platform= for vendor filtering, tenant_id= for a single rank) and by showing how the result shape changes between modes. This goes beyond the schema's type-level 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 opening sentence defines a specific resource and operation: a live ranking of agent-run businesses by a settlement-derived track record. It explicitly differentiates from sibling catalog tools with 'the catalog is how you enter; the arena is how you're ranked,' which lets an agent distinguish it without opening other schemas.

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

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

The description maps each invocation mode to a goal: 'Omit args for the top of the board; platform= to filter by vendor type; tenant_id= for one business's rank.' It also names the sibling alternatives (federation_catalog_agents / federation_catalog_platforms) and states the condition that selects them versus this tool, so routing is explicit.

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

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

Annotation contradiction: the annotation declares readOnlyHint=true, but the description says calling this tool 'SELF-HEALs' a suspended/frozen root and that the decay lifts within ~30 seconds. That describes a state-changing side effect, contradicting the readOnlyHint annotation.

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

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

The description is front-loaded with the core purpose and mandate, then efficiently explains implicit attestation, when to self-heal, the key not-lifted case, identity reading, and the return value. Every sentence contributes substantive information with no filler.

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

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

For a zero-parameter tool with no output schema, the description is complete: it explains the liveness context, side effects, timing, who is non-lifted, how identity is resolved, and what is returned. The only issue is the annotation contradiction.

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 covers 100% of it. The description adds a concrete example ('call federation_attest with arguments {}'), which is harmless and useful for a no-argument tool. No parameter clarification is needed beyond this.

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 ('Attest') and a clear resource ('your manager root') tied to a named liveness mandate (CO 144). It distinguishes this tool from siblings by framing it as an explicit liveness-attestation action with self-healing 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?

It explicitly states when to call the tool ('when idle, or to SELF-HEAL a mandate-decayed root'), notes that activity already counts and attests implicitly, and gives a clear exclusion: an explicit operator freeze is NOT lifted by attesting. This is strong when/when-not 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 this as read-only, non-destructive, and non-open-world Ratio, so the description doesn't need to reiterate safety. It adds meaningful behavioral details: return shapes for each arg mode, the filter combos, and the edge case that retired platform values are accepted but return 'honest-empty list'. This goes beyond annotations and gives the agent a clear picture of what to expect.

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

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

The description is dense but well-organized: it opens with the tool's core purpose, then systematically explains argument modes, and ends with a concrete example. Every sentence adds information; the only minor issue is the amount of detail could be reduced slightly without losing clarity, but it's still efficient.

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

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

Given the absence of an output schema, the description provides detailed return structures for each argument mode, including the summary fields. It discusses edge cases (e.g., retired platforms return honest-empty list) and explains the relationship with a sibling tool. This covers all essential aspects the agent likely 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?

Schema covers 100% of parameters, so baseline is 3. The description adds value by explaining the combined behavior of omitting vs passing each parameter and the exact return structures for each call mode (grouped fleet vs filtered list). For 'agent', it states it returns a full card, which the schema does not specify.

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 ('Browse') and specific resource ('ComOS network agent fleet') and immediately distinguishes what it does ('what each agent does and who it serves'). It contrasts with sibling tool federation_catalog_platforms ('agents are the operators you hire; platforms are what you become'), making its unique role 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?

Explicitly instructs when to omit args (fleet view), when to pass 'serves' or 'platform', and when to use 'agent' for a single agent's card. It also names the sibling platform tool and explains the relationship, giving clear guidance on when to choose 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 declare readOnly/idempotent/non-destructive, but the description adds context beyond that: 'a preset is not a platform and never counts in summary.total (CO 455),' plus the side and parent interplay ('When present, side is ignored'). This enriches behavioral understanding well past annotation coverage.

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

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

The description is dense and information-rich, front-loaded with the main purpose and ending with an example. Every sentence contributes value, though it is somewhat long; however, given the tool's complexity, the length is justified and there is no redundancy.

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

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

With no output schema, the description fully specifies the return shape: '{ platforms: Array<{ key, label, posture, availability, replaces, tagline, description }>, summary: { total, side, parent } }'. It also explains recursive descent, presets, and side semantics, making it complete for an agent to use 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% for both parameters, but the description adds practical examples (vendor: retail/bookings; customer: messaging/shipping) and clarifies the top-level vs. parent behavior more concretely. This goes slightly beyond the schema's own descriptions, so a 4 is warranted.

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 'Browse' with a clear resource ('the ComOS network's composable platforms') and characterizes it as a 'recursive catalog.' It differentiates from siblings by contrasting platforms with agents: 'platforms are what you become; agents are the operators you hire to run them.'

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

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

Explicitly states when to use this tool: 'answers an agent shopping the network' and 'renders the human nav.' It names an alternative, federation_catalog_agents, and explains the division of responsibility, giving clear when-to-use vs. when-not-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?

Despite annotations already indicating readOnly/idempotent/destructive hints, the description adds substantial behavioral context: progressive disclosure semantics, session persistence via mcp-session-id, 24h idle expiration, re-entering re-scopes, the authoritative reply structure (platform_tools, composed_tool_defs), and the REST twin mechanism. This goes far 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 long but information-dense, with every sentence conveying a distinct aspect (purpose, flow, reply, session, REST, info tenants, example). It is front-loaded with the main purpose and uses semicolons and bullets (by structure) to organize related details. Slightly verbose but warranted by 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?

Given the tool has one parameter and no output schema, the description compensates by explaining the return value ('Returns: { platform_tools: [...] }'), session behavior, REST alternative, and usage example. It covers all necessary context for an agent to 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 with a description and 100% coverage. The description adds value by showing the exact call pattern ('{"tenant_id":"<tenant_id>"}'), relating tenant_id to session scoping, and noting its use in the REST twin body. This enriches the parameter semantics beyond the bare 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: 'Enter a tenant to receive its tool surface (progressive disclosure).' It uses a specific verb ('enter') and resource ('tenant'), and distinguishes from siblings by referencing federation_list_tenants as the prerequisite step. The description also notes the distinction from info tenants, making the 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?

The description provides explicit workflow guidance: 'list tenants with federation_list_tenants, then enter one here.' It explains when re-entering is needed ('re-enter to resume'), how info tenants behave (serve read-only knowledge directly on tools/list), and gives a REST twin alternative. This clearly tells an agent when and how to use this tool 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that it reflects live constants, discloses no private standing, and outlines enforced brakes and detection mechanisms. This goes beyond the annotations, providing useful behavioral context 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?

The description is very long and dense, covering many details. It is front-loaded with the core concept but then expands into extensive detail. While each sentence carries information, it is not concise. The structure is organized but could be trimmed for a tool description.

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?

Since there is no output schema, the description fully explains what the tool returns, listing all components of the governance model. It also provides an invocation example and clarifies what it does not disclose. This is comprehensive for a zero-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?

There are zero parameters, so the schema is complete. The description provides an example invocation, which satisfies the need for parameter semantics. Baseline for zero parameters is 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 identifies the tool as explaining federation governance, detailing the autonomy ladder, clamps, and related concepts. It is distinct from siblings by topic, though it doesn't explicitly name an alternative. The purpose is specific and not a tautology.

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 when-to-use or alternative tools are mentioned. The description implies usage for understanding the governance model, and the caution to verify against live tools is advisory rather than selection guidance. No exclusions are provided.

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

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

Annotations already declare this is a safe, read-only, idempotent, non-destructive, non-open-world operation. The description adds meaningful behavioral context: it explains what is returned (Markdown help text covering quick-start, tenant_id, cart persistence, product IDs, auth, workflows) and discloses the tool_defs behavior for served-but-unlisted root tools, including how to invoke them directly or via federation_act.

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 purpose and the call-first instruction. It is dense and somewhat jargon-heavy in the CO 529 disclosure section, but each part earns its place by explaining return content, parameter behavior, and an example invocation.

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 help tool with no output schema and one well-documented optional parameter, the description is complete. It covers what the tool returns, why it should be called first, how tool_defs works, and which topics the help text addresses, giving an agent enough to invoke and use it correctly.

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

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

Schema description coverage is 100% for the single tool_defs parameter, so the baseline is 3. The main description still adds value by explaining that tool_defs can be 'all' or a specific tool name and by describing the downstream invocation path for unlisted tools, though some of this repeats the schema parameter description.

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

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

The description states a specific verb and resource: get usage instructions for the MCP federation. It tells the agent when this is most important ('CALL THIS FIRST') and scopes the content to product IDs, authentication flow, and federation tool usage, making it clearly distinct from operational siblings like federation_act or federation_search.

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 strong usage context: 'CALL THIS FIRST to understand how to use tools correctly' and explains how to use the optional tool_defs parameter to retrieve unlisted tool schemas. It does not state when not to use this tool or name alternative help/about siblings, so it misses the top level of explicit 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description doesn't need to repeat safety. The description adds valuable context: ordering (oldest→newest), limit behavior, permission requirements ('journal:read on your federation OAuth bearer'), and ownership scope ('only replay tenants your manager root owns'). It also states the return value. 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 yet comprehensive. It front-loads the core purpose, then covers usage context, permissions, return, and an example. Each sentence adds value without being repetitive. Slightly verbose but well-structured.

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 (2 params, no output schema, no nested objects) and strong annotations, the description covers the essentials: when to use, what it returns, permissions, and example. It doesn't detail entry structure or error handling, but for a read-replay tool this is sufficient.

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

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

Schema description coverage is 100%, with both parameters (tenant_id and limit) well-described in the schema itself. The description adds an example invocation and emphasizes 'with only your tenant id,' but it doesn't provide additional semantic meaning beyond the schema. 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 clearly states the tool's function: 'Replay your agent journal oldest→newest' with a specific purpose ('reconstruct your intent and resume where you left off'). It distinguishes itself from siblings by mentioning it pairs with federation_journal_append and is meant for cold session starts. The reference 'CO 230-001' adds specificity.

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: '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 notes the pairing with federation_journal_append. While it doesn't explicitly say when not to use, the usage context is clear and distinguished from other federation tools.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description adds value by detailing safety (never returns secrets), the attestation chain head inclusion, and the location of the full chain. It clarifies the return structure and explicitly states what it never returns, which is beyond 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 clear sections (purpose, return, usage, location). It's mostly concise, but the phrase 'Never returns any challenge or secret' appears twice, adding slight redundancy. Still, it's efficient and front-loaded with the core purpose.

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 simple (one optional param, no output schema), and the description explains the return format explicitly, safety guarantees, and where to find additional attestation chain details. Annotations cover read-only/idempotent hints, so the description is complete 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?

Schema coverage is 100% and documents manager_id as 'The root to read; defaults to the caller.' The description rephrases this as 'Omit manager_id to read your own,' which adds negligible meaning beyond the schema. Baseline 3 is appropriate since the schema handles parameter explanation adequately.

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 'Read a manager root's bound public key' with specific resource (bound public key) and verb (Read). It distinguishes from sibling tools like federation_key_bind (write) and federation_key_challenge (challenge) by focusing on the read/status aspect.

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 usage guidance by explaining the default behavior ('Omit manager_id to read your own') and the context of verification ('A counterparty verifies this root's signatures against it'). It doesn't explicitly exclude alternatives but implies when to use (reading status) without mentioning when not to use.

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?

Even with strong annotations (readOnlyHint, idempotentHint, non-destructiveHint), the description meaningfully adds depth: the disclosure that results are 'computed live', 'never asserted', and that an empty history returns null percentiles + sample_count 0 ('an honest empty') are material behaviors well beyond the structured metadata. The 'Verify, don't trust' line frames the appropriate mental model.

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 and well-organized, but has clear redundancy and a weak closer ('Example: call federation_latency with arguments {}' adds no value beyond what the documented param pattern already conveys). The empty-history caveat ('an honest empty, not a fabricated number' / 're-call after traffic') appears nearly verbatim twice, which wastes words in what could be a tightly structured description.

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 properly documents the response shape '{ p50, p95, p99, sample_count }' and edge-case behavior (null percentiles for empty history). It also covers freshness/computation source and operational advice. Combined with strong annotations and a small parameter surface, the guidance is complete and digestible for the 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?

The input schema already has 100% coverage of the two parameters, so the schema is doing the heavy lifting. The description does add some framing — 'scope to one tool' for `tool` and 'widen/narrow the sample window' for `limit` — which reinforns semantic meaning. However, it's largely reinforcing schema-provided context rather than unlocking semantic info unavailable elsewhere.

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

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

The description uses specific, precise language to define what's measured ('MEASURED p50/p95/p99 in ms of recent authenticated tool executions'), units, and the underlying data source (gateway's own audit records). It crisply differentiates from potential sibling observability tools by framing it as the 'verifiable answer to is it really sub-100ms?' — the grounding in 'real recorded call durations, never asserted' adds distinctive value.

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 clearly conveys when to use it, including specific invocation patterns ('Omit args for the whole surface; tool= to scope; limit= to widen/narrow'), which provides implicit when-to-use guidance tied to use case. It stops short of a formal 5 because it never names alternative tools for when guidance would fall to another tool (e.g., 'use X instead for...'), though the rich usage examples largely compensate.

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 adds some context beyond annotations, such as the return format and that it returns all tenants (no filtering). However, it does not disclose potential pagination, response size limits, or any rate limits. Annotations already declare read-only and idempotent, so the bar is lower, and the description adds useful return details.

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 front-loaded with the core purpose, but the return type example is slightly repetitive and could be trimmed. Still, every sentence serves a purpose and it is not verbose.

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 (zero params, no required inputs), the description is complete enough for an agent to invoke it correctly. It includes return structure and an example. The lack of an output schema is compensated by the in-description return format. Slight deduction for not explaining possible status values or edge cases.

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?

Despite zero parameters, the description clarifies that no arguments are needed and includes an example with empty arguments, which adds value over the empty schema. With no parameters to document, a baseline of 4 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 lists all tenants in a federation and specifies the returned data (tenant IDs, names, and status). It distinguishes from siblings like federation_tenant_info and federation_list_agents by explicitly focusing on tenant discovery.

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 instructs the agent to use this tool to discover which tenants it can interact with, providing a clear use case. It differentiates from related tools by focusing on tenant enumeration, though it doesn't name alternatives. The example invocation reinforces when to use it.

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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to repeat those. It adds valuable behavioral context by explaining that it returns a route (not a transaction), is deterministic, and returns unroutable:true when no platform serves the intent, which goes beyond the annotations. It also describes the return structure, adding transparency 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 detailed but somewhat long; however, it is well-structured with a clear explanation, examples, behavioral notes, and return structure. Every sentence adds value, but the final example 'call federation_search with arguments {}' is redundant and slightly confusing, as it omits the required intent argument, which slightly detracts from conciseness.

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 purpose as an entry point to route to platforms, the description fully covers what the tool does, what it returns, and how to use it. It includes edge cases (unroutable), deterministic behavior, and the next steps, making it complete for an agent. The output schema is absent, but the description compensates by listing the fields returned, so this is essentially 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 coverage is 100% with both parameters (intent and limit) described in the schema, so the baseline is 3. The description adds meaning beyond the schema by explaining the intent parameter with examples and clarifying that limit controls ranked platform returns, plus it describes the output structure (ranked platforms with fields like platform_id, why_matched, score, entry_points). This enriches the parameter semantics beyond the schema alone.

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

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

The description clearly states the tool routes a natural-language intent to a platform on the ComOS network, and it explicitly positions itself as 'the first thing to call,' distinguishing it from sibling tools. It uses a specific verb ('route') and resource ('intent to platform') and contrasts with other federation 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?

The description provides explicit guidance on when to use the tool: 'the first thing to call' for routing an intent, and it clarifies that it returns a ROUTE, not a transaction, followed by acting on the platform with the chosen tenant. It also notes the behavior for unroutable intents, giving clear usage context and alternatives implicitly by stating what the tool does not do.

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, but the description adds substantial behavioral context: values are computed from real GL rows, never asserted, read live, and the tool is always free. It also explains the defect nature of unbalancedEntries and that solvent requires both conditions, going well 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?

The description is well-structured and front-loaded with the core question and answer. It is slightly longer than strictly necessary due to repeated CO references and the example call, but every sentence contributes meaningful context about behavior, output, or usage.

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 listing all return fields and their meanings, explaining the solvency condition, and describing the data source and safety profile. It is complete for a parameterless read-only tool and fits well within the large sibling toolset.

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 schema description coverage is 100%, so the baseline is 4. The description reinforces this by providing an example call with arguments {} and by explaining what each returned field means, which is the relevant semantic content for this parameterless 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 description clearly states the tool's purpose: it returns the dollar ledger's live solvency invariant for the Com float, including reserve, outstanding, margin, and unbalancedEntries. It distinguishes itself from siblings by naming its unique invariant and referencing the same 'verify, don't trust' posture as federation_latency and federation_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 gives clear context for when to use the tool: to check whether the Com float is actually backed, and it notes that this is public, read-only, and always free. It does not explicitly name alternative tools to use instead, but the use case is unambiguous and the sibling differentiation is implied through the unique solvency invariant.

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 explicitly states the return format ({ tenant: TenantInfo | null, found: boolean }), which is a key behavioral trait not covered by annotations. Annotations already provide readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about the return value, which goes beyond what annotations state. However, it doesn't detail potential side effects or error conditions, but since it's a read-only operation with good annotation coverage, a 4 is appropriate.

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

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

The description is two sentences: one states the purpose and return value, the other provides a concrete example. No filler, every sentence earns its place. The key information (what it does, what it returns, how to call it) is front-loaded and concise.

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 simple with a single parameter, a clear return type, and strong annotations. The description covers the purpose, return format, and gives an example. There's no output schema, but the description explicitly defines the output shape. For its simplicity, it is complete. It could mention error cases, but those are likely covered by the 'null' return and are not critical for selection.

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

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

Schema description coverage is 100%, so the schema already documents the tenant_id parameter. The description adds a concrete example of how to pass the parameter, which reinforces usage. Although the description doesn't add new semantic meaning beyond the schema, the example improves clarity, so this exceeds the baseline 3 for full coverage.

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

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

The description clearly states the tool retrieves detailed information about a specific tenant, including metadata, description, and configuration. The verb 'Get' combined with the resource 'tenant information' is specific and distinguishes it from sibling tools like federation_list_tenants (which lists all tenants) and federation_update_tenant (which modifies 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 implies usage when a single tenant's details are needed, contrasting with listing tools. It provides an example call with arguments, which guides the agent on how to invoke it. However, it doesn't explicitly mention alternatives or when not to use it (e.g., when a list of tenants is needed), though the sibling tool names and the singular focus implicitly handle this.

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 idempotentHint=true, but the description adds valuable behavioral detail: it returns a thesis object with specific components, includes an 'honest door-state caveat' (open via tokened apply; tokenless never admits), and notes it is 'relayable verbatim.' This goes beyond the annotation safety profile and informs the agent of what to expect.

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

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

The description is moderately concise but contains some redundancy, e.g., it says 'Returns the thesis: ...' then later 'Returns: A thesis object: ...' covering similar ground. However, it is front-loaded with the purpose and usage, and the redundancy is minor. It remains readable and informative.

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 explains the return object's structure (thesis, play, what-you-could-become, etc.) and the caveat. It also points to related tools for further help. Given the tool's simplicity (no parameters, read-only), the description is complete and leaves little ambiguity.

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 0 parameters, and the schema covers 100% of them (none). The description even provides an example call 'with arguments {}' to confirm no input is needed. Since there are no parameters, the baseline is 4, and the description adequately addresses this.

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 explicitly distinguishes from federation_help ('federation_help tells you HOW; this tells you WHY'), making the unique function unambiguous. It also specifies it returns a thesis object, so the outcome is clear.

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: 'Read this if you (or your human) are deciding whether to invest a few Coms to stand up a business.' It also directs users to federation_help for how-to details, providing both when-to-use and when-not-to-use guidance. The mention of alternate resources (federation_help, how-to, on-ramp manifest) strengthens the routing.

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 non-destructive nature. The description reinforces this ('Read-only', 'performs no transaction') and adds value by revealing the exact content shape (markdown) and composition (in the comos-federation voice). The zero-arg note further clarifies call semantics. Slight deduction for not mentioning caching, speed expectations, or what could go wrong.

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

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

Three efficient sentences. Each earns its place: resource identification, read-only safety, return type, zero-arg note, and usage example. No redundancy with the already-clear tool name. Perfect structure in under 60 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 zero-param, read-only, no-output-schema tool, this description covers all bases: what, safety, return format, call signature. Slight deduction for not explicitly stating what kind of knowledge is NOT included (e.g., 'for federation system info, use federation_help') to prevent misuse, but this is minor for such a simple 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?

With zero parameters, the description needs to simply state this. The description does so clearly and even gives an example call ('call how_to_about with arguments {}'). There's nothing more the description could add about parameter semantics.

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

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

The description clearly states this reads the 'How to use ComOS' walkthrough knowledge. It specifies the exact resource ('How to use ComOS' knowledge in the comos-federation voice) and distinguishes it from siblings by noting it's a knowledge read. The scope ('composed walkthrough knowledge as markdown') is specific and useful.

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 clearly implies when to use this tool (when the agent needs ComOS usage knowledge). The zero-arg and identity-free notes clarify usage constraints. While it doesn't explicitly name alternatives or when-not-to-use, the zero-arg and read-only nature creates clear context. It could explicitly mention checking federation_help or about_us_about for other info needs.

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; the description reinforces this by saying 'Public and read-only; discloses, does not gate.' It adds extra context about the nature of the instruments (terms agents operate under) and the markdown output format, which is useful beyond 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 and well-structured, starting with the primary purpose, then the instrument list, operational context, and a usage example. No redundant sentences; every sentence adds 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?

Given the single parameter with full enum coverage and no output schema, the description adequately explains what the tool returns (raw markdown) and provides an example call. It is complete for a read-only retrieval tool.

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

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

Schema coverage is 100%, and the description explicitly enumerates the allowed values for the 'document' parameter with examples and a usage example, adding clarity beyond the schema by explaining the representation of each enum value.

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

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

The description clearly states the tool fetches legal instruments as raw markdown, listing specific documents (Terms, Privacy, DPA, retention). It distinguishes from siblings by specifying the exact resources available; no other sibling tool appears to handle legal instruments.

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 usage context: 'read them the way you read the pricesheet' and states it is public and read-only. It does not explicitly mention when not to use or alternatives, but the context is strong enough given the specific document list.

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