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 already declare read-only and idempotent behavior, reducing the burden. The description adds meaningful context: the score is derived from ComOS-signed counters and is 'a fact surfaced, not a verdict rendered,' indicating it doesn't imply qualitative judgment. It also explains the return structure and confirms no destructive operation. This is above baseline but not exhaustive (e.g., no mention of rate limits or auth).

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 yet well-structured: it opens with a clear metaphor and purpose, then gives usage patterns, explains the derivation of the score, ties to sibling tools, and describes return formats. Every sentence adds value, and the example at the end reinforces understanding 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 there is no output schema, the description must fully describe return values, and it does so in detail (leaderboard fields, tenant_id row/rank). It also covers filtering, limit behavior, and the relationship to other tools, leaving no major gaps for a tool with only three optional parameters. The description is complete for an agent to invoke and interpret outputs.

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 the three parameters, so baseline is 3. The description adds value by explaining how each parameter affects the output (e.g., tenant_id= returns a single entry and rank, platform= filters the board) and provides an example call. It clarifies that limit does not affect rank or total_ranked, which is not in the schema. This goes beyond mere schema repetition.

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's purpose: ranking agent-run businesses by settlement-signed reputation. It uses a specific metaphor ('live arena') and explicitly distinguishes itself from sibling tools ('the catalog is how you enter; the arena is how you're ranked'), making it 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 usage patterns: omit args for top board, use platform= to filter by vendor type, use tenant_id= for a single business's rank. It also hints at when not to use it (raw volume is not the metric) and ties it to catalog tools as the entry point. However, it doesn't strictly state when not to use the arena (e.g., for raw volume queries) beyond the 'not raw volume' phrase, so it's not as explicit as possible.

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?

Annotations declare readOnlyHint and idempotentHint, and the description adds valuable context beyond that by explaining the grouping behavior (collapsing size/color variants), the return structure (results with tenant_id, status, data/error, summary), and the optional auth. No contradiction with annotations; the description meaningfully enhances understanding.

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: purpose, usage, alternative, tenant source, auth, return structure, and an example. It is front-loaded with purpose and each sentence contributes value. Slightly long but not excessively verbose, earning a high 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?

Given there is no output schema, the description thoroughly explains the return format and example call. It covers all necessary aspects: grouping behavior, per-tenant results, summary counts, and the key differentiator from sibling. The description is complete for an agent to understand 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 description coverage is 100%, so parameters are fully documented in the schema. The description barely adds beyond the schema (only reiterates tenant_ids and auth_token), which matches the baseline of 3. It doesn't provide additional meaning not already in 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 the tool searches product families across multiple tenants, explicitly contrasting with the sibling tool federation_catalog_search_multi for exact variant SKUs. This distinct purpose is stated with a specific verb and resource, making it easily distinguishable.

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 explicit guidance on when to use this tool ('Prefer this for discovery') and when not to ('Use federation_catalog_search_multi when you need exact variant SKUs'). It also mentions tenant_ids source and auth_token optionality, offering clear context for selection.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, and the description adds meaningful behavioral detail: the search is public, auth_token is optional, searches run in parallel, and the response includes per-tenant status/error fields. This gives the agent operational expectations beyond the schema.

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

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

The description is information-dense and includes return shape, alternatives, and a usage example, but it is slightly run-on and could be split into clearer sentences. No sentence is wasted, though the example duplicates some schema 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?

Given there is no output schema, the description fully documents the return structure with results and summary fields, and covers parallel execution, auth, data source for tenant_ids, and the primary alternative tool. This is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra semantic value by explaining the tenant_ids source (federation_list_tenants), the "all" convenience value, and the optional auth token behavior, plus a concrete invocation example.

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

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

The description clearly states the tool searches products across multiple tenants in parallel, with a specific flat (one row per variant) shape. It distinguishes itself from the sibling grouped search by explicitly naming that alternative.

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

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

The description gives explicit guidance on when to use this tool versus federation_catalog_search_grouped_multi, saying the grouped variant is for browse/discovery flows and token-efficient rollups. It also tells the agent where tenant_ids come from (federation_list_tenants) and that "all" is allowed, providing clear usage context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. Beyond this, the description adds real value: it discloses the return shape ({ tenant_id, catalog_version, fetched_at }), clarifies the returned value is an 'opaque hash' suitable only for change-detection, and includes a concrete example call. Loses a point only because annotations already carried much of the safety-profile weight.

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?

Organized around a clear narrative arc: what it does, when to use it (vs. alternative), what it returns, and how to call it. Every sentence earns its place, but could be tightened — the example call at the end is slightly redundant given the schema documents the parameter.

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 simplification surface (1 param, 100% schema coverage, complete annotations) is comprehensively covered: return type, change-detection semantics, staleness consequence ('you will reference SKUs that no longer exist'), and a copy-pasteable example. No output schema exists, so the explicit return shape disclosure closes the 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% (the sole tenant_id param is fully documented in the schema). The description adds a working example invocation with the parameter, which is helpful, but doesn't reveal non-obvious semantics beyond what the schema already states. This is the textbook baseline-3 case where the schema does the heavy lifting.

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

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

Uses a specific verb+resource pattern: 'Return a fingerprint of the current catalog for a tenant' with the clarifying metaphor 'fingerprint' and the purpose 'a cheap way to tell whether the catalog changed.' This clearly distinguishes it from sibling tools like federation_catalog_search_multi (search), federation_catalog_platforms (enumeration), and federation_catalog_agents (agent listing).

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 rich workflow context: compare the returned version against a previous catalog_search result, re-run catalog_search if they differ before mutating operations like order_create. The 'cheap way' phrasing implicitly contrasts against the more expensive alternative (re-running the search), and the explicit guidance on what to do when versions diverge ('re-run catalog_search to get current product_ids') gives the agent actionable when-to-use direction.

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, so the agent knows it's safe. The description adds valuable behavioral context: the promotion label is 'SEPARATE, disclosed' and 'never a rank input' – crucial to understand that promotions don't affect ranking. It also describes the eliminated block, showing resource cost of constraints. This goes beyond annotations, though not deeply into rate limits 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 lengthy but information-dense, covering purpose, parameters, usage, and output. However, the final sentence 'Returns: Qualifying candidates with aligned comparable facts, fact-only organic_rank, separate promotion label slot, and an eliminated block.' duplicates the earlier sentence 'Returns qualifying candidates with aligned facts and a FACT-ONLY organic_rank, plus a SEPARATE, disclosed `promotion` label slot (never a rank input), and an `eliminated` block...' This redundancy could be trimmed, but otherwise it's 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 there is no output schema, the description fully covers expected outputs, including the organic_rank, promotion label, and eliminated block. It also explains the input structures thoroughly, covering both candidate scope modes. For a tool with this complexity (4 params, nested objects), the description is complete and self-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 coverage is 100%, but the description adds substantial semantic detail: it explains the structure of constraints with concrete examples ({dimension:'geo',op:'includes',value:'NG'}) and clarifies the candidates property's two valid forms. Also explains limit default via 'default 20' in schema, but description doesn't repeat it. The description adds value over schema by explaining the elimination semantics and the discover mode, making parameter usage clear.

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: 'Compare federation tenants on their structured choice_profiles to pick one for a need.' It identifies the specific resource (federation tenants) and the action (compare to pick), and distinguishes it from siblings like federation_catalog_search_multi (which searches) and federation_choice_get (which retrieves a single choice profile) by focusing on comparison and selection.

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: 'Use this to choose a tenant before buying via the catalog/order path.' Also explains the two candidate scope modes ('after a catalog search' vs '{discover:true,vertical?} to find candidates by need'), giving clear context for selecting the appropriate input format. It indirectly differentiates from search tools by requiring a prior catalog search for tenant_ids, and provides alternatives implicitly through the candidates scope.

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, covering the safety profile. The description adds context about the return payload (freshness timestamp, promotion label), which is useful. It doesn't mention side effects or permissions, but given the strong annotation coverage, this is adequate.

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 redundant: it repeats the return values ('Returns: ...') after already mentioning them earlier. The example 'call federation_choice_get with arguments {}.' is misleading because tenant_id is required but omitted. This prevents the description from being concise or 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?

For a simple read tool with one parameter and no output schema, the description adequately covers what it returns (choice_profile envelope, freshness, promotion label) and when to use it. It's complete for typical invocation, though the misleading example slightly detracts.

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 for the single parameter tenant_id with a clear description ('The tenant whose profile to fetch'). The description adds no extra meaning beyond what the schema already establishes, so baseline 3 applies.

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

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

The description clearly states the tool fetches a tenant's full choice_profile, freshness, and promotion label. It uses a specific verb ('fetch') and explicit resource ('tenant's choice_profile'), and distinguishes itself by referencing federation_choice_compare as a prior step, which sets it apart from siblings like federation_canon_get.

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

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

The description gives explicit guidance: 'Use after federation_choice_compare has narrowed to a single tenant.' This tells the agent when to invoke it and implies it's not for initial selection. It doesn't explicitly name alternatives, but the reference to a specific prior tool provides clear context.

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

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

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 and idempotentHint, so the description's 'Read-only' is redundant, but it adds valuable context: it reflects live constants, discloses no private manager standing, and lists the exact content of the returned object. This goes beyond the annotation basics.

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 lengthy but well-structured, starting with the core purpose and then enumerating the specific topics covered. Each sentence adds meaningful detail about what the tool returns, though it could be trimmed slightly without losing 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 tool has no parameters and no output schema, the description fully covers what the tool does and what it returns, including a worked example of the governance model, accountability structure, and enforcement mechanisms. It is complete for an informational 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?

The tool has zero parameters, so per the rubric, baseline is 4. The description correctly notes the call requires no arguments ('call federation_governance with arguments {}'), which is sufficient.

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: explaining how the federation governs its agents, listing the autonomy ladder, manager ceiling, override clamps, escalation path, confidence thresholds, and manager-standing enforcement. It is specific and distinct from the many sibling federation_* tools, which focus on actions or status 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 usage as a read-only reference for understanding governance constants and notes that it does not disclose individual manager standing. It doesn't explicitly mention alternatives or when not to use it, but the context is clear: it's an informational tool for governance model details.

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 aligns without contradiction. It adds value beyond the annotations by specifying the return type (Markdown) and the content topics (tenant_id, product IDs, auth, workflows), which gives the agent expectations for the response.

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

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

Two tightly packed sentences plus an example. It front-loads the purpose, states the critical usage guidance, summarizes the return payload, and gives an example call 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, read-only help content—the description covers purpose, usage priority, return format, content areas, and an invocation example. Nothing essential is missing for an agent to select and 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?

There are zero parameters, and the schema coverage is 100% (empty object), so there is little to add. The description explicitly notes 'call federation_help with arguments {}', confirming the expected invocation and satisfying the 0-param 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?

Description uses specific verb 'Get usage instructions' with resource 'MCP federation', and the 'CALL THIS FIRST' directive positions it as the meta-help tool distinct from the many federation_* siblings. It clearly communicates its role as an onboarding/instruction tool rather than a domain operation.

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 call this first to learn correct usage, including product IDs and authentication flow, which serves as a clear when-to-use. It doesn't name alternatives or exclusions, but because this is a unique help tool, 'CALL THIS FIRST' provides sufficient contextual 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 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 indicate read-only, idempotent, non-destructive, but the description adds substantive behavioral context: it is public, requires no token, returns a specific JSON shape, and references the underlying document '/.well-known/comos-vendor.json'. The explicit statement 'This tool changes nothing' reinforces the read-only nature beyond the annotation booleans.

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-structured: it leads with purpose, then return value, then application steps, then exact return shape, then an example. Each sentence adds distinct value with minimal redundancy. Slightly long but efficient for the information conveyed.

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

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

Given no output schema, the description fully compensates by detailing the return object structure ('{ offer: ..., how_to_apply: { step_1, step_2, note } }'), pricing tiers, auth requirements, and the relationship to the well-known document. The tool is simple and the description leaves no important behavior unexplained.

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 optional 'channel' parameter, so the schema already provides full semantics. The description does not discuss the parameter, but it does include an example 'call federation_offer with arguments {}', which hints that no parameters are needed. This is baseline 3 as the schema carries the parameter detail.

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: 'Read the ComOS network's vendor offer', clearly stating what the tool does. It further differentiates from siblings by declaring it 'public and read-only, no token needed' and explicitly contrasts it with federation_apply ('this tool changes nothing; it is the door's window, and federation_apply is the door').

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

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

The description provides explicit usage context: read the offer first, then apply via federation_apply. It states 'then call federation_apply with it', naming the alternative and giving a clear sequence. It also notes the tool requires no token, so the agent knows when it can be invoked without auth.

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 substantial behavioral detail: it specifies that reads, lifecycle exits (disconnect, unsubscribe, cancellation), and the settling sale path are never priced; it explains the pricing curve format and that reprices are effective-forward. This goes well beyond what annotations provide, and no contradictions exist.

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

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

The description is dense but every sentence carries meaningful information: the purpose, the pricing format, exemptions, the effective-forward policy, the source of truth, and a return structure example. It is front-loaded with the main idea and structured logically. No filler or redundancy.

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

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

With no output schema, the description must document the return format, and it does: a detailed object with title, peg, live, take_rate, price_form, lifecycle, failure_modes, and platforms. It also includes an example call. Given the simplicity of the tool (no parameters), this is fully complete 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, so schema coverage is trivially 100%. Per the rubric, 0 params merits a baseline of 4. The description doesn't need to explain parameters and instead focuses on the return structure, which is appropriate. No further semantic augmentation 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 opens with a clear statement of purpose: 'The federation pricesheet — every platform's per-act Com prices.' It identifies the resource (pricesheet) and the action (read). It also distinguishes itself from sibling tools by focusing specifically on pricing rather than catalog searches or other federation operations, making the uniqueness obvious.

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 this tool is useful (to look up per-act costs) and adds context like 'Any tool not listed is free' and 'the price you read is the price applied.' It does not explicitly name alternatives or exclusions, but the context is sufficient for an agent to infer when to call it. A clear 'use this when you need pricing details' statement would push it to 5.

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

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

Annotations already declare 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?

Goes beyond annotations by describing the exact out-of-scope behavior ('returns uncited(out_of_scope) rather than an error') and future version plans. No contradiction with readOnlyHint/idempotentHint, and it adds value by detailing edge-case responses.

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, spending sentences on version history and future plans. While informative, it could be more concise and front-load the essential usage. The 'Returns' section is minimal but clear.

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 comparison tool, it covers the core functionality, limitations (only 'current' id), and error behavior. However, the misleading example with empty arguments and lack of explicit parameter breakdown leave some gaps. Overall adequacy is modest.

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 has no parameter descriptions and the tool description does not explicitly explain what corpus_id_a and corpus_id_b mean, though their purpose is inferable. The example call with empty arguments is misleading, given two required params, reducing semantic clarity.

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 'Compare two corpora by id' which clearly identifies the action and resource. It differentiates from sibling tools like introspection_corpus_query by focusing on comparison, though the versioning caveat and malformed example slightly muddy the core message.

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 context ('pass it for both sides to sanity-check the surface') and explains the behavior for invalid ids. However, it does not explicitly state when to use this tool over alternatives or provide exclusion criteria, leaving some ambiguity.

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

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

Annotations already cover safety (readOnlyHint=true, destructiveHint=false), so the bar is lowered and the description does not contradict them. It adds Phase 3.5 scope context (intra-repo vs future cross-repo), which is useful. But it says nothing about how disagreement is detected, reliability of results, or whether the tool is heuristic/probabilistic — useful behavioral context given openWorldHint=false.

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

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

Three sentences and front-loaded with the core purpose. But 'highly load-bearing for honest epistemic surfacing' is fluff that earns no functional value, and the example 'call introspection_corpus_probe_disagreement with arguments {}' is trivially unhelpful. The return value line is structured as 'Returns:' which aids scanning, but the overall text carries minor waste.

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 and only minimal annotations, the description must define expectations for results, but it only states 'Returns: The detected points of corpus disagreement' without format, granularity, or scope. For a moderately complex tool with two parameters and no output schema, it also fails to clarify how this differs from introspection_corpus_compare and how disagreement results should be interpreted.

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 carry parameter meaning. It explains 'repo' restricts to intra-repo disagreement, which is genuinely helpful, but the required parameter 'topic' receives no explicit explanation beyond the tool's own name and general description. At 0% coverage, the description should explicitly describe both parameters, and it only partially handles one.

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 states the tool queries the corpus for points where artifacts disagree on a topic, with a specific verb+resource. It roughly distinguishes itself from siblings like introspection_corpus_query and introspection_corpus_compare by focusing on disagreement. However, it never defines what 'disagree' concretely means (contradictory claims, differing answers), and the phrase 'highly load-bearing for honest epistemic surfacing' is subjective marketing rather than functional 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?

Only guidance given is that optional 'repo' restricts to intra-repo disagreement and that cross-repo is a future tool. No explicit when-to-use versus introspection_corpus_compare, introspection_corpus_probe_scope, or introspection_system_coverage_gaps, all of which could plausibly overlap. No exclusions or alternatives named, so an agent has no basis to pick this over adjacent 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral detail beyond those annotations: results are 'topical map with citations' and uncovered topics return 'uncited(out_of_scope)'. There is no contradiction with 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 short and front-loaded, but it wastes space with the redundant line 'Returns: The scope of the requested corpus region' and includes a misleading empty-arguments example. These extra sentences reduce the clarity that brevity would otherwise provide.

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?

Without an output schema, the description does a reasonable job conveying the main return shape: a topical map with citations, or an out-of-scope result. However, it leaves unclear how citations are structured, how repo identifiers are specified, and the invalid example makes the invocation contract less 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 description coverage is 0%, so the description must carry parameter meaning. It explains `topic` as the subject asked about and `repo` as optional one-repo scoping, but the example 'call introspection_corpus_probe_scope with arguments {}' is invalid because `topic` is required. Parameter constraints and format expectations are otherwise left unexplained.

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

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

The description opens with a specific verb and resource: 'Ask the corpus what it covers on a given topic.' It clearly distinguishes this as a scope/coverage probe from sibling tools like introspection_corpus_query or introspection_corpus_probe_disagreement, and states the output forms: 'topical map with citations' or 'uncited(out_of_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 clear usage context: use it to ask what the corpus covers on a topic, with `repo` as an optional scoping mechanism. It does not explicitly list when not to use it or name alternative tools, so it misses the highest bar, but the intended usage 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 mark this as read-only and non-destructive (readOnlyHint: true, destructiveHint: false). The description adds meaningful behavior beyond that: cited results resolve through the pinned manifest, every content_excerpt is verified as a substring of the artifact, and the returned object shape includes a reason for uncited results. These are useful guarantees for an agent deciding whether to trust the output.

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

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

The description contains redundant return information: it first specifies the exact return shape, then later says 'Returns: The corpus nodes matching the query.' The example call with `{}` is questionable and could encourage an invalid invocation. The text is front-loaded but not tightly structured, and the 'Phase 3.5' parenthetical adds little.

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 does a solid job of explaining what the agent can expect: cited vs uncited envelopes, citation verification guarantees, and optional repo filtering. It does not cover edge cases like pagination, empty results, or how to phrase a query, but for a read-only corpus query tool the provided context is largely 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 coverage is 0%, so the description must carry the parameter documentation burden. It explains that `repo` optionally filters candidate manifest entries, but it does not elaborate on `question` beyond the phrase 'Ask the corpus a question'. The example call with arguments `{}` is misleading because `question` is required by the schema, so it may cause an agent to invoke the tool invalidly.

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 action: 'Ask the corpus a question'. It specifies the resource (corpus), the two possible return envelopes ({kind: "cited", ...} or {kind: "uncited", ...}), and the optional repo scoping. This distinguishes it from sibling corpus tools like generate, compare, or 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?

The description implies when to use the tool: whenever the agent needs to query the corpus. However, it does not explicitly address alternatives such as introspection_corpus_compare or introspection_corpus_generate, and it provides no when-not-to-use guidance. The repo filter is mentioned but no exclusions or alternative tool references are 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?

While annotations already state readOnly and idempotent, the description adds crucial behavioral detail: 'Never silently reconciles drift' and the exact return envelope for evidence or absence. This goes beyond annotation to explain how the tool behaves, making it transparent.

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

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

The description is front-loaded with the core purpose and then expands into details. It's somewhat long but each sentence adds meaning; no redundancy. The example call is helpful.

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 and examples. It also includes provenance and key behavioral caveat, making it self-contained 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 tool has zero parameters)Skip. Per rubric, baseline is 4 for 0 params. The description correctly confirms it takes no arguments and provides return structure, so it doesn't need to explain 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 explicitly states it returns the dependency graph of change orders across all repos, detailing nodes, edges, interest edges, and drift reports. It clearly differentiates from siblings like introspection_system_change_reach by focusing on the full graph structure rather than reachability or other aspects.

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 what the tool does but not when to use it versus alternatives like introspection_system_change_reach or introspection_system_diff. It lacks explicit exclusions or guidance on selecting this tool, though the purpose 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 readOnly and idempotent, so the description adds valuable behavioral context: edge traversal types, provenance details, default values, and the two response envelope variants. It does not cover performance implications, but that is acceptable for an introspection read tool.

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

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

The description is dense but includes redundancy: the final 'Returns: The set of surfaces a change reaches' restates the opening, and the example 'call introspection_system_change_reach with arguments {}' contradicts the required origin_slug parameter. These additions waste words and mislead the 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 complex graph-traversal tool with no output schema, the description covers the return shape, provenance, evidence chain, parameters, and defaults. It leaves internal references like 'D8' unexplained, but the essential information for correct invocation 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 description coverage is 0%, yet the description thoroughly explains all three parameters: origin_slug with a concrete example, max_hops with default and bounds, and include_parent_child with its toggle semantics. This fully compensates for the schema's lack of 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 the tool's purpose: 'Return the REACH of a change' with explicit scope ('every artifact across every registered repo') and traversal semantics. It distinguishes itself from sibling introspection tools by focusing on reach and provenance rather than graph structure or 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 implies usage for anyone needing to understand what artifacts a change reaches, and it details parameters and defaults. However, it never explicitly contrasts with alternative tools or states when not to use it, leaving the when-to-use guidance implicit.

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, and the description reinforces read-only behavior. It adds valuable context about return shapes (evidenced vs no_evidence_available) and the meaning of snapshots, going beyond 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 a single information-dense paragraph that front-loads purpose and then details parameters and return types. It includes an example call, which is helpful but slightly extends length. Still, every sentence adds necessary information.

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

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

For a read-only tool with 3 parameters, the description covers all essential aspects: purpose, parameters, defaults, return format, and failure modes. Annotations handle safety, and the output shape is fully described.

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 fully compensates by explaining each parameter: since (ISO timestamp), limit (integer ≤1000), repo (string, defaults to comai-plan, reads subtree). It also clarifies default behavior, which the schema alone doesn't convey.

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's a time-series read of honesty-ratio snapshots, specifying the exact data (chain_length, honesty_ratio_percent, NN-state counts, per-unit states). It distinguishes itself from sibling introspection_* tools by focusing on climb history over a time window.

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 defaults (7-day window, max 200 snapshots, default repo) and parameter usage, but does not explicitly contrast with alternative tools like introspection_system_change_graph. Still, the use case is well-scoped.

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 clear. The description adds useful context about the return format (evidenced vs no_evidence_available) and mentions accountability and PR links, but it does not fully describe behavior such as pagination or error handling. This is adequate given annotations but not exceptional.

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

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

The description is a single dense paragraph, which is not ideal for quick scanning. It includes a reasonable amount of information but is front-loaded with technical jargon. The example at the end is helpful but could be formatted better. It is not overly verbose, but the structure could be improved with bullet points or separation.

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 (multiple modes, multiple parameters, no output schema), the description provides a good overview of modes and return types, but it lacks explicit parameter requirements and edge-case explanations. It does its job but leaves gaps in how the tool handles invalid combinations (e.g., mode='touched_co' without co_id). Since the output schema is absent, the description could have explained the output structure more thoroughly.

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 description coverage is 0%, meaning the description must explain the parameters. It does partially: it explains mode and its enum values, and mentions co_id and agent_id in the context of modes. However, it does not explicitly define the purpose of co_id and agent_id beyond the mode context, and it doesn't specify that co_id is required for touched_co and agent_id for agent_autonomous. Parameters like co_id and agent_id are not fully described. This is a significant gap given the 0% 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 defines the tool as querying a CO-management decision log with a focus on evidenced graph nodes, and it provides mode-specific examples that distinguish it from likely siblings (e.g., other introspection tools). However, the phrasing is dense and could be more direct about the core purpose, and it doesn't explicitly differentiate it from every sibling, but it is specific enough.

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 mode-specific guidance: e.g., mode='touched_co' with co_id, mode='agent_autonomous' with agent_id, and mode='escalated'. It explains what each mode returns, which implicitly tells when to use the tool. However, it does not explicitly state when not to use it or name alternative tools, but the context is strong.

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, so the tool's safety profile is known. The description adds value by explaining the response structure (evidenced vs no_evidence_available) and the optional repo scoping, which are not covered by annotations. However, it does not go deeper into behavioral details like error handling or caching, which annotations partially cover. Given the annotations, a 3 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 well-structured and front-loaded with the core purpose. It includes concise details on parameters, response types, and an example call. While it is somewhat long, each sentence contributes useful information without redundancy. It earns a high score for efficiency.

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

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

Given there is no output schema, the description explains the two possible response shapes ({kind: 'evidenced', value, chain} or {kind: 'no_evidence_available', reason}). It also mentions the prerequisite for valid node IDs and the optional repo scoping. This covers the essential context for successful invocation. Some details like error codes or edge cases are omitted, but they are not critical for a simple read-only retrieval.

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%, but the description compensates by explaining node_kind values and node_id types ('path | name | id'). It also clarifies the optional 'repo' parameter and provides a usage example. This adds meaningful semantics beyond the raw schema enums and string types.

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

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

The description clearly states the tool returns a confidence number for a federation node, including the evidence chain. It specifies node kinds and response formats, distinguishing it from sibling introspection tools like probe or list_nodes. The verb 'return' and resource 'confidence number' make 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 implies usage when confidence metrics are needed and provides a prerequisite by referencing introspection_system_list_nodes for valid node IDs. It does not explicitly compare with alternatives, but the context is clear enough to know when to call this tool. There is no misleading 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 annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by disclosing the two possible return shapes ({kind: 'evidenced', ...} or {kind: 'no_evidence_available', ...}) and the conditional requirement for scope_id when scope_kind=tenant. While it doesn't cover rate limits or authentication, the added behavioral context is meaningful.

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 brief and front-loaded with the main purpose. However, it is slightly redundant, saying 'Returns ...' and then again 'Returns: The set of known coverage gaps,' which wastes a little space and could be condensed.

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 lack of output schema and param descriptions, the description provides some useful context (return envelope, conditional scope_id) but leaves gaps: the content of Gap[] and chain is not defined, and the repo parameter is unexplained. This is adequate but not fully complete for an agent to use with confidence.

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 explain the parameters. It clarifies scope_kind (enum values) and scope_id (required if scope_kind=tenant), but the 'repo' parameter is not mentioned at all. The example only uses scope_kind, leaving the optional repo parameter's purpose undocumented.

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: 'Enumerate structural coverage gaps' with concrete examples (silent tools, artifacts with no eval, un-probed tenants). This distinguishes it from sibling introspection tools by focusing on coverage gaps rather than probing, diffing, or listing nodes.

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 context for when to use the tool is implied by the purpose and scope_kind parameter, but there is no explicit guidance on when to use this instead of alternative introspection tools (e.g., introspection_system_probe) or when not to use it. No exclusions or alternatives are mentioned.

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, so the safety profile is clear. The description adds that node IDs must come from introspection_system_list_nodes, which is useful prerequisite context, but it does not elaborate on error behavior, edge cases, or the exact nature of the structural difference returned.

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 concise, leading with the purpose and then parameter hints. However, the example 'call introspection_system_diff with arguments {}' is misleading because the tool requires four arguments, and the example provides no illustrative value. This detracts from 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 read-only comparison tool with no output schema, the description covers the essential context: what it does, what it returns (structural difference), and where valid node IDs come from. It does not define the exact structure of the diff, but that may be acceptable given the tool's simplicity and the presence of related introspection tools.

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. It explains baseline_kind as a constant 'since', provides the ISO date format, and references node_kind/node_id from the confidence tool. This adds meaning beyond the schema's constraints, though it does not explicitly describe all parameter purposes or the meaning of the return structure.

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 (compare) on a specific resource (node's evidence) against a baseline date, clearly distinguishing it from sibling introspection tools like confidence. It also specifies the return type, 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 implies usage (comparing evidence to a baseline) and references a sibling tool ('same as confidence') for parameter context, but does not explicitly state when to use this over alternatives like introspection_system_change_graph or when not to use it. The mention of valid node IDs from list_nodes provides prerequisite 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 adds rich behavioral detail beyond the annotations: it details the per-node shape (kind / id / display_name / activation_state with enumerated values / defect_categories? / last_touched_at), explains the conditional return format ({kind: 'evidenced', ...} or {kind: 'no_evidence_available', reason}), and even provides the change-order context. This goes well beyond the readOnlyHint and idempotentHint annotations, giving the agent a precise understanding 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 longer than strictly necessary but is well-structured and front-loaded with the core purpose. It includes a detailed return format and an example call, which are useful. However, the change-order context ('Added by change-order 2026-05-27-010...') is not essential for tool usage and adds slight verbosity. Overall, every sentence contributes, but a bit of trimming would improve 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 that there is no output schema, the description thoroughly explains the return structure and conditional behavior. It covers the single optional parameter, the node shape, and the different response kinds. The tool's complexity is low, and the description provides all necessary information for an agent to call and interpret the result. It is complete for its scope.

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

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

The sole parameter `repo` is documented in the description ('Optional `repo` scopes the artifact list to one repo (Phase A)'). The schema has no description for it (coverage 0%), but the description fully compensates by explaining its purpose and scope. This is more than sufficient for a single optional 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's function: 'Enumerate every artifact, tool, and tenant the federation knows about, with the activation state needed to render picker UIs.' It names the exact resources (artifacts, tools, tenants) and the specific verb 'enumerate', making the purpose unambiguous. It also implies a distinction from sibling tools by focusing on the complete node list with activation state.

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: it is used to render picker UIs, and it mentions the optional `repo` parameter to scope the artifact list to one repo. While it does not explicitly name alternative tools, the distinct scope and purpose make when-to-use implied. It does not provide explicit exclusions but is clear enough for an agent to select it when listing nodes.

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 covered. The description adds that every repo is currently active in the federation registry, which is useful context. It doesn't describe any side effects or additional behavioral nuances beyond what annotations provide, leading to a baseline score given 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 front-loaded: the first sentence states the purpose, and the rest adds return format and usage hints. Every sentence is informative without redundancy. It includes a changelog reference, which is extra but not 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?

For a zero-parameter, read-only tool with good annotations, the description is complete: it specifies the return structure and how to use it. No output schema exists, but the description explicitly outlines the return format, covering what the agent needs to know.

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 correctly notes the call requires arguments {}, and it explains the return structure. There is no parameter schema to compensate for, so the baseline is high. The description adds meaning by telling the agent that 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's purpose: listing ComOS repositories contributing to introspection, and it differentiates from siblings by noting it's specifically for discovering repo IDs to pass to introspection_system_climb_history. The verb 'List' with a specific resource is present. However, it doesn't contrast with other introspection_system_* tools beyond one mention.

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 repo ids to pass to introspection_system_climb_history, providing a clear usage context. It doesn't explicitly state when not to use it or list alternatives, but the inclusion of a direct cross-reference is helpful 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 indicate read-only and idempotent. The description adds that it returns a full evidence trace (vs collapsed number) and mentions repo scoping behavior. It doesn't contradict annotationsic. Some clarity on the output shape could be added, but with annotations covering safety, this is adequate.

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, but the example 'call introspection_system_probe with {}' is misleading because required parameters exist. The 'Returns' line is somewhat redundant. Still, it's brief and structured fairly well overall.

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

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

For a tool with 3 parameters and no output schema, the description provides some context (evidence trace, repo scoping, node list source) but lacks details on output structure or how the trace is organized. It's adequate but not complete for a complex tool like this.

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 has no descriptions (0% coverage). The description only mentions that repo is optional and scopes to one repo. It doesn't explain node_id or node_kind meanings beyond referencing confidence's argument shape, which is vague if the agent isn't familiar with that tool. Lacks concrete guidance on parameter values and formats.

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 returns the full evidence trace for a node, distinguishing from the collapsed number returned by similar tools like introspection_system_confidence. The verb 'Return' and resource 'full evidence trace' are specific, and the mention of 'same argument shape as confidence' helps differentiate from siblings.

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

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

Provides guidance on valid node ids (from introspection_system_list_nodes) and optional repo scoping, implying when to use this tool. However, it doesn't explicitly state when to choose this over the confidence tool or other alternatives, though it hints at the distinction between full trace vs collapsed number.

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.

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

The description states 'Read-only, no claim required' which aligns with annotations (readOnlyHint, idempotentHint, destructiveHint=false). It adds useful context about what the tool returns (target, count, posts/comments) and clarifies the three reading modes. It does not contradict any annotations and goes beyond them by explaining the social network 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 a single dense paragraph that covers all key points without redundancy. It front-loads the purpose, then explains targets and returns. It includes a reference to a field guide section, which adds context but could be seen as tangential. Overall, it is efficiently structured and not overly 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 that this is a simple read-only tool with no output schema, the description is sufficient. It explains the three modes and their parameters, the return structure, and the authentication nuance. It lacks edge-case notes (e.g., errors, pagination behavior) but these are not critical for this tool's scope.

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

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

The input schema covers 100% of parameters, so baseline is 3. The description adds value by explaining when each target requires specific parameters: submolt for target='submolt', post_id for target='comments'. It also mentions sort options and that manager_root is optional for authentication, providing clarity 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 this tool reads Moltbook, a specific social network for AI agents. It differentiates from sibling tools like moltbook_post by focusing on read-only access. It specifies three distinct targets (feed, submolt, comments) with precise meanings, making the tool's 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 context: 'Use it to listen before you contribute' and notes that Moltbook is outside the federation, referencing a field guide. It implies this is for reading public content without requiring claims. However, it does not explicitly mention when NOT to use it or compare to alternatives like federation_journal_read or web_research, which could be improved.

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