ComOS Federation Gateway

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

The annotations already declare readOnly, idempotent, and non-destructive. The description adds that it returns markdown and is zero-arg, which aligns with the annotations. It provides a bit of extra context without contradicting the metadata.

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 concise but has some redundancy (e.g., 'Read About ComOS' followed by 'Read-only' and 'Returns'). It is not overly verbose, but could be tightened without losing 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?

Given the simplicity of the tool and lack of an output schema, the description sufficiently indicates the return format (markdown) and the general content (about ComOS). It covers the essential information without needing further detail.

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 no parameters, and the description explicitly notes 'Zero-arg', making it clear that no arguments are needed. Although the schema already covers this, the description reinforces it effectively.

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

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

The description clearly states that the tool reads about ComOS and returns the knowledge as markdown. It is straightforward and distinguishes itself as an 'about' resource among the many sibling tools.

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

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

The description does not explicitly explain when to use this tool versus alternatives, but given its self-explanatory nature (fetching the about page), the intended use is implicit. Minimal guidance is provided beyond the read-only nature.

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

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

The annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that: the score is a trust-weighted function of settled transactions, derived from ComOS-signed counters, and is presented as a fact rather than a verdict. 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 information-dense and well-organized, covering definition, usage modes, catalog relationships, return shapes, and an example. It is slightly longer than strictly necessary, with a few phrases (like the CO 200 detail) that could be trimmed, but overall each section earns its place.

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

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

With no output schema, the description compensates by detailing exact return shapes for both the default/leaderboard mode and the tenant_id mode, including field names, nullability, and the filter field. It also explains the relationship to catalog tools and the scoring rationale, making it comprehensive enough for confident tool 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?

The input schema covers all three parameters (limit, platform, tenant_id) with complete descriptions, so the schema does the heavy lifting. The description only reiterates the purpose of platform and tenant_id and mentions limit in the return format; it adds little beyond schema 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 a live arena ranking agent-run businesses by settlement-signed reputation, with distinct operations for the full board, platform filtering, and single-tenant lookup. It also distinguishes itself from catalog siblings by explaining the catalog-to-arena relationship.

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

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

Explicit usage instructions are provided: omit args for the top of the board, use platform= to filter by vendor type, and tenant_id= for one business's rank. It also names companion tools (federation_catalog_agents/platforms) and clarifies that the catalog is for entry while the arena is for ranking.

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 readOnly, idempotent, non-destructive. The description adds valuable behavioral context: the decay lifts within ~30s, no review/operator involvement, identity read from token, and the return value (refreshed liveness standing). It does not contradict annotations and provides meaningful additional transparency.

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

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

The description is moderately lengthy but every sentence adds value: purpose, implicit vs explicit, when to call, self-heal behavior, limitations, identity, and return. It is front-loaded with the core purpose. Slightly dense but not verbose, hence 4 rather than 5.

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 parameters, no output schema, and simple annotations, the description fully covers the tool's purpose, usage, outcomes, and edge cases (e.g., operator freeze). It is complete for a read-only, parameterless attestation tool.

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

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

There are zero parameters, so schema coverage is 100% by default. The description provides an example call with empty arguments and confirms that identity is derived from the token, which is sufficient for this parameterless tool. Base score 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's purpose: 'Attest your manager root is alive (CO 264 liveness mandate)'. It specifies the resource (manager root) and the action (attest), and distinguishes from other federation tools by explaining its unique role (explicit attestation when idle or self-healing a decayed root).

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

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

Provides explicit when-to-use guidance: 'call this when idle' and for self-healing mandate-decayed roots. It also states what it does NOT do (does not lift explicit operator freeze) and notes that activity already implies attestation, so it's only needed in specific circumstances. This clearly differentiates from alternatives.

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

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

The annotations (readOnly, idempotent, non-destructive) are consistent with the description's implied read-only behavior. The description additionally explains the return structure, which adds transparency beyond the annotations, but does not cover 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 unnecessarily verbose and repetitive. It states the filtering logic twice (once in the intro and once in the 'Returns' section) and mixes narrative with examples. A more concise version could convey the same information in half the length.

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

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

The description covers the tool's purpose, parameter usage, return formats, and its relationship to a sibling tool. It does not mention error cases or potential limitations, but for a read-only catalog browse, it is quite complete.

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

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

The description explains each parameter's role: 'serves' and 'platform' filter, 'agent' retrieves a full card. It also clarifies the default behavior when args are omitted. While the schema already includes descriptions, the description adds context about grouping and pairing, slightly enhancing understanding.

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: 'Browse the ComOS network's autonomous agent fleet' and what it does (what each agent does and who it serves). It also distinguishes itself from the sibling 'federation_catalog_platforms' by noting the pair relationship.

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 instructions on when to omit args, when to pass 'serves' or 'platform', and when to use 'agent'. It also mentions pairing with federation_catalog_platforms, but does not explicitly state when to choose this tool over others like search or list tools.

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

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

The annotations already mark the tool as readOnly, idempotent, and non-destructive. The description adds valuable context beyond annotations: presets are not platforms and never count in summary.total (CO 455), and the same call works at every depth. This explains edge-case behavior without contradicting 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 dense but every sentence earns its place. It front-loads the core purpose ('Browse... recursive catalog'), then explains side, presets, parent, relationship to sibling, return structure, and an example call—all without redundancy. The length is justified given the tool's recursive nature and missing output schema.

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

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

The description is fully complete for this tool: it explains navigation (top-level vs parent), side filtering, presets (what they are and how they affect counts), return shape with exact fields, and the relationship to agents. Since there is no output schema, the description carries the burden of return-type explanation, and it does so 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 provides full coverage of both parameters, giving baseline 3. The description adds concrete meaning with examples: side='vendor' returns sell-on platforms (retail, bookings, services) and side='customer' returns run-with tools (messaging, shipping, marketing). For parent, it gives an example of parent='messaging' returning channels (email, sms, dm), and notes that side is ignored when parent is present (also in schema). This enriches the parameter understanding.

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 'Browse the ComOS network's composable platforms as a recursive catalog' with a specific verb and resource. It also distinguishes itself from the sibling federation_catalog_agents by explaining the difference: '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?

It explicitly names an alternative tool (federation_catalog_agents) and contrasts when to use which. It also indicates the tool 'answers an agent shopping the network' and works at every depth, providing clear usage context. The side parameter semantics (vendor vs customer) are explained with examples, leaving no ambiguity about when to use the tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description correctly adds that it's a 'Public read' with optional auth_token, which is useful context. The return structure is disclosed. Minor deduction for not explicitly stating rate limits or parallel execution details, but the description adds good value on top of 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 dense but the last sentence is essentially a duplicate of the tool name and adds bulk without much value. The rest is well-structured and information-dense, front-loading the key grouping behavior before diving into return shapes.

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 moderately complex multi-tenant search tool with 5 params and no output schema, the description covers the key semantic behavior (grouping), input source, output shape, error wrapping, and example invocation. No critical gaps identified.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant semantic meaning by explaining what 'grouped' means ('collapses size/color variants into one row'), describing the return shape (priceRange, variantCount, options, nested variants), and explaining the relationship to the alternative tool. The example helps invoke correctly. Minor deduction because the limit parameter semantics ('Maximum variants to fetch per tenant before grouping') could be further clarified, but overall strong param explanation.

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

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

The description clearly states the tool searches product FAMILIES (grouped variants) across multiple tenants. It explicitly distinguishes itself from siblings like federation_catalog_search_multi (for exact variant SKUs), making the purpose and differentiator unmistakable.

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

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

Provides explicit when-to-use guidance ('Prefer this for discovery'), names the alternative tool for exact SKUs ('Use federation_catalog_search_multi when you need exact variant SKUs'), and explains where tenant_ids come from (federation_list_tenants or 'all'). This is exemplary 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. The description adds meaningful behavioral context: parallel execution, the ability to pass 'all' for active tenants, the public-read nature making auth_token optional, the exact return shape, and an example call. This adds value beyond the boolean hints without any contradiction.

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

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

Every sentence earns its place: purpose, behavior, alternatives, parameter origin, auth note, return shape, and example — all in three dense sentences. Well front-loaded with the core action, no fluff.

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

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

For a multi-tenant search tool with two required and three optional parameters, the description covers parallel execution, tenant enumeration, authentication nuance, output format, and example invocation. Even without an output schema, the return shape is fully documented. This is as complete as one could expect.

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

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

Schema coverage is 100%, so baseline 3 applies. The description goes further by explaining tenant_ids accepts 'all', clarifies the semantic of flat results (one row per variant), and includes a full invocation example. Minor deduction because more detail on limit/category would have been nice, but the description clearly supplements the schema.

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

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

The description states 'Search products (flat — one row per variant) across multiple tenants in parallel' — a specific verb, resource, and scope. It explicitly distinguishes from the sibling tool by calling out 'flat' and by cross-referencing the grouped variant, making it clear what makes this tool unique.

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 use the alternative: 'Use federation_catalog_search_grouped_multi for browse/discovery flows to get token-efficient family rollups.' It also tells where tenant_ids comes from (federation_list_tenants) and notes auth is optional, covering both tool selection and prerequisites.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description adds useful behavioral context: the result is a cheap opaque hash, it represents catalog state, and it is intended for change-detection. It also discloses the exact return shape, which the absent output schema would otherwise leave unknown.

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

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

Every sentence earns its place: purpose, comparison workflow, consequence of ignoring a change, return shape, and a concrete invocation example. It is compact yet high-density, 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 simple read-only, one-parameter tool with no output schema, the description is complete: it explains purpose, usage, return fields, and gives an example. Nothing important is left unstated.

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 fully documents tenant_id with 100% coverage, so the baseline applies. The description only repeats the parameter in an example call without adding new constraints or semantics 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?

States a specific action and resource: 'Return a fingerprint of the current catalog for a tenant.' It clearly distinguishes itself from sibling catalog_search tools by framing the output as an opaque change-detection hash rather than a search result.

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

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

Explicitly tells the agent when to use it: compare the returned catalog_version against the one from a previous catalog_search result, and re-run catalog_search if they differ before acting on product_ids. This gives both a concrete workflow and an alternative action.

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 transparency about the output semantics by clarifying that 'organic_rank' is fact-only and the 'promotion' label is separate and disclosed. This goes beyond the annotations (read-only, non-destructive) by explaining how rankings are presented. No contradictions with annotations are present.

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 verbose and contains redundancy, notably repeating the full description of return values ('Returns qualifying candidates...') twice. The structure is somewhat stream-of-consciousness and could be tightened. While not egregiously long, the repetition 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?

Given the absence of an output schema, the description compensates by detailing the return structure (organic_rank, promotion, eliminated block) and explaining the candidate scope. However, it fails to mention the 'limit' parameter, which is a required gap. The overall context is adequate but not fully complete.

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

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

The description thoroughly explains three of the four parameters: 'need', 'constraints' (with examples), and 'candidates' (with two modes). However, it omits the 'limit' parameter entirely, leaving its purpose and default unspecified. This gap reduces completeness in parameter 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's purpose: comparing federation tenants based on their choice profiles to select one. It explicitly mentions the use case 'choose a tenant before buying', distinguishing it from catalog search or other tools. Despite a minor typo ('pick a need' instead of 'pick a tenant'), the overall intent is 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 usage context by explaining the two modes for the 'candidates' parameter (after a catalog search vs. discovery) and states the intended scenario ('before buying via the catalog/order path'). It does not explicitly enumerate exclusions or alternative tools, but the guidance is sufficient for typical 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details about the promotion label being null if not promoted, and that it returns freshness. It doesn't repeat annotation claims and adds context beyond them.

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 three sentences and an example. The example 'arguments {}' is misleading since tenant_id is required, which slightly reduces clarity. However, overall it is compact and 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 getter with one parameter, no output schema, and annotations covering safety, the description adequately explains the return values (choice_profile envelope, freshness, promotion label). It also gives usage context. It doesn't describe error scenarios, but that's acceptable for this tool type.

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

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

The input schema has one parameter (tenant_id) with a clear description. Schema coverage is 100%, so the description doesn't need to add parameter details. The description doesn't provide additional semantic value beyond the schema, thus the baseline score of 3 is appropriate.

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

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

The description clearly states the tool fetches a tenant's full choice_profile, including freshness and promotion label. It distinguishes from sibling tools by explicitly positioning it after federation_choice_compare, ensuring the agent knows this tool is for retrieving all published data for one tenant.

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

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

The description provides explicit usage context: 'Use after federation_choice_compare has narrowed to a single tenant'. This gives a clear when-to-use. It doesn't list when-not-to-use or alternatives, but the context is strong enough for an agent to differentiate.

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/destructiveHint, and the description adds substantial behavioral mechanics beyond them: session persistence via mcp-session-id, 24h idle expiry, re-entering re-scopes, the authoritative reply structure (platform_tools/platform_tool_defs vs. composed_tool_defs), and REST twin behavior. No contradiction with annotations is present.

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 every major sentence adds distinct value (progressive disclosure, session lifecycle, REST twin, info tenants, return shape). However, it is somewhat verbose with minor redundancy: "authoritative" appears twice, and the final example sentence largely repeats schema documentation. Slightly trimmed would be ideal.

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 high complexity (session scoping, progressive disclosure, REST twin, no output schema), the description is remarkably complete: it explains the reply contents, session expiry/re-entry, re-scoping semantics, and the REST alternative. Minor gaps remain, such as error behavior for invalid/unknown tenant ids and clearer guidance on whether info tenants need to be entered.

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% (tenant_id with example "about-us"), so the baseline is 3. The description adds contextual meaning: tenant ids come from federation_list_tenants, appear in the REST twin body as {"tenant_id":"<entered tenant>"}, and are used in the worked example. This elevates it above baseline but does not reach 5 since the schema already documents the parameter well.

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

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

The opening sentence states a specific verb+resource+outcome: "Enter a tenant to receive its tool surface (progressive disclosure)." It clearly distinguishes this from sibling federation_list_tenants (list vs. enter) and explains its gateway role, including info-tenant behavior. This is unambiguous and well differentiated.

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

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

Explicit sequencing is given: "list tenants with federation_list_tenants, then enter one here." The description also names an alternative access path ("REST twin: POST /tools/<name>"), describes when re-entry is needed (24h idle expiry), and notes that info tenants serve read-only knowledge directly on tools/list. This is strong when-to-use guidance.

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

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

The description explicitly discloses behavioral traits: it's read-only, reflects live constants, and discloses no specific manager's private standing. The annotations already set readOnlyHint=true and idempotentHint=true, so the description adds context about what the returned data represents and that it's a live snapshot. It doesn't contradict 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 dense but well-structured, front-loading the core purpose and then detailing what the returned object contains. It has a clear order: purpose, read-only note, and output details with an example. It is a bit verbose but each sentence serves a 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?

Given the tool's complexity, the description is quite thorough. It covers the autonomy ladder, manager ceiling, always-escalate path, confidence thresholds, and manager-standing enforcement, and details the returned object's contents. No output schema is provided, so the description compensates by listing the returned model fields. The example call adds practical guidance.

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

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

With zero parameters, the schema covers 100% by default, so baseline is 4. The description adds value by mentioning the example call with empty arguments, clarifying that no parameters are needed, which is useful.

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

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

The description clearly explains the tool's purpose: it describes the federation's governance model, including the autonomy ladder, manager ceiling, and enforcement details. It explicitly states it is read-only and provides the live governance constants. While it mentions 'how the federation governs its agents,' it doesn't explicitly distinguish it from siblings, but the detailed focus on governance model sets it apart.

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 states this is read-only and reflects live constants, implying it's for looking up governance rules rather than modifying them. It mentions returning a governance-model object and even provides an example call. However, it doesn't explicitly state when to use this over alternatives like 'federation_agent_status' or 'federation_solvency', but the read-only nature and specific focus provide 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?

Annotations already declare readOnlyHint true, destructiveHint false, and idempotentHint true, covering its safe read-only nature. The description adds value by specifying it returns Markdown help text and listing the exact topics covered (quick-start, tenant_id requirement, cart session persistence, product IDs, authentication, workflows). 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—two sentences plus an example—and front-loaded with the critical directive 'CALL THIS FIRST'. Every sentence earns its place: what it does, why to call it first, what it returns, and an example. No fluff.

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

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

Given the tool's trivial complexity (no params, no output schema, no nested objects) and rich annotations, the description is fully complete. It covers the purpose, usage directive, return type, content coverage, and an example. There is nothing missing for an agent to use it correctly.

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

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

The tool has zero parameters, so the schema offers no semantics. The description compensates by providing an example call with empty arguments {} and implicitly clarifying no parameters are needed. This meets the baseline of 4 for no-parameter tools.

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

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

The description uses a specific verb ('Get') and resource ('usage instructions for the MCP federation'), clearly stating its function. It distinguishes itself from sibling tools by being the introductory/usage guide for the federation, explicitly marked as 'CALL THIS FIRST'.

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

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

The description explicitly instructs the agent to call this tool first ('CALL THIS FIRST') and explains why: to understand product IDs and authentication flow. It provides clear context on when to use, effectively making it the entry point for the federation toolset.

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 (readOnly, idempotent, non-destructive) and the description adds concrete behavioral context: permission requirement, ownership scope, and return order (oldest→newest). 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?

Two crisp sentences plus a return note and example. Every sentence adds value—no fluff, purpose is front-loaded.

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

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

Tool is simple (2 params) with no output schema, but the description explains return format, usage context, permissions, and gives a concrete example. It fully covers what an agent needs to invoke it effectively.

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 'limit' and 'tenant_id' documented. The description adds a minor note that only tenant_id is needed, but doesn't enhance parameter 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 replays the agent journal oldest→newest, with a specific purpose (reconstruct intent at cold session start). It also names the paired write tool (federation_journal_append) to distinguish from the write 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 states when to use ('start of a cold session') and provides exclusions (only replay tenants owned by your manager root) plus permission requirements (journal:read on federation OAuth bearer). This is unambiguous 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 and idempotentHint, which are consistent with the 'Read' verb. The description adds value by stating 'Never returns any challenge or secret' and describing the attestation chain head inclusion, providing clarity beyond annotations about what the tool will not do.

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

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

The description is informative but slightly redundant, as 'Never returns any challenge or secret' appears twice. It also includes a verbose explanation of the attestation chain. While well-structured, it could be tightened without losing 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?

With no output schema, the description fully covers the return value expectations, including the attestation chain head and the public key fields. It also provides an example and explains the difference from full chain retrieval, making it complete for the tool's simplicity.

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 provides 100% coverage for the single parameter with 'defaults to the caller.' The description reiterates this with 'Omit manager_id to read your own' and gives an example call, but adds minimal new meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Read a manager root's bound public key' with specific resource and verb. It lists the returned fields and distinguishes from related tools like federation_key_bind and federation_key_challenge by focusing on reading rather than binding or challenging.

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 that omitting manager_id reads the caller's own key and mentions that counterparties use it for signature verification. It also points to a well-known URL for the full chain, providing context for when this might be needed. While it doesn't explicitly state when not to use it, the purpose is reasonably clear and distinct from siblings.

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, and the description productively enlarges on them: values are 'never asserted', 'computed live from real recorded call durations', and empty history produces an 'honest empty' rather than a fabricated number. This is exactly the right kind of disclosed uncertainty. Slight deduction for the redundant duplication of the empty-history caveat, which muddies otherwise strong transparency.

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

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

Clearly front-loaded and the first sentences are excellent, but the back half falls apart into repetition: the phrase 'An empty history returns null percentiles + sample_count 0 (an honest empty, not a fabricated number) — re-call after traffic' appears almost verbatim twice (right after 'never asserted' and again in the Returns section), and the final 'Example: call federation_latency with arguments {}' is confusing filler. Every sentence should earn its place; two of them didn't.

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 introspection tool with zero required params, no output schema, and a small well-specified params set, this is largely complete: it covers the return shape { p50, p95, p99, sample_count }, the marginal-case behavior (empty history), and the data provenance ('CO 292' audit source). It doesn't really explain the distribution semantics behind p50/p95/p99, but nothing important is missing.

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

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

Schema coverage is 100% with descriptive text on both params ('Restrict the percentiles to one tool', 'Max recent samples to scan (default 500, cap 5000)'). The description layers on helpful semantic framing — 'tool= to scope to one tool; limit= to widen/narrow the sample window' — which adds a modicum of meaning, though it largely re-words 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?

Specific verb+resource+scope: 'the MEASURED p50/p95/p99 (in ms) of recent authenticated tool executions, computed live from the gateway's own audit records.' The description crisply distinguishes this from siblings as the verifiable, measured source of truth for latency, and even positions it against the rival claim 'is it really sub-100ms?'. Purpose is unmistakable even before the title is read.

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

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

Provides clear usage context: 'Omit args for the whole surface; tool= to scope to one tool; limit= to widen/narrow the sample window,' plus when to re-call ('re-call after traffic'). The 'verify, don't trust' heuristics signal intent. Loses a point for not naming explicit alternatives or stating when NOT to use this tool vs. a sibling — especially notable in a large federation_* namespace.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context by detailing the return structure (tenants array with id, name, status) and confirming no arguments are needed, going beyond the annotation-only information.

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, with the primary action front-loaded, followed by the return type, usage guidance, and an example. Every sentence adds value 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?

For a zero-parameter, read-only list tool with strong annotations, the description covers purpose, return structure, and usage example. No output schema exists, but the inline return type is sufficient. The tool is simple enough that no additional context is needed.

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

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

The tool has zero parameters, making schema coverage trivially complete. The description reinforces this with an example showing 'arguments {}', which is helpful despite the schema already indicating no properties. No additional meaning needed.

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

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

The description clearly states the tool lists all available tenants in the federation and specifies the return fields (IDs, names, status). This distinguishes it from sibling tools like federation_create_tenant or federation_delete_tenant, which involve mutations.

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 'Use this to discover which tenants you can interact with,' providing a clear use case. It doesn't explicitly mention alternatives or when not to use, but the purpose is unambiguous for a listing operation.

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 only say readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description goes further by disclosing that the signature is the authentication, that queue ownership is enforced by construction, that expired acts are skipped, and that past-delivery acts dead-letter. It stops short of explaining whether a successful drain durably removes acts from the broker or what happens if the client fails after receiving them, which matters for a drain operation.

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

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

The description is dense and front-loaded, with the purpose stated first and each sentence carrying meaningful security or behavioral detail. However, the misplaced and inaccurate example at the end weakens the structure: it is presented as an invocation template while being impossible given the required parameters, and it should be corrected or removed.

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 mutating, non-idempotent tool with no output schema, the description covers identity, auth, queue scoping, expiry/dead-letter behavior, and the response shape. Gaps remain around error-code semantics, whether acts are removed atomically on collection, and redelivery behavior if the caller never succeeds, plus the incorrect empty-arguments example undermines the completeness of the calling guidance.

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

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

Schema coverage is 100%, so a baseline of 3 is warranted, and the description does add useful context by explaining that node_id is an authenticated identity rather than a filter and that signature covers a canonical envelope. However, the final example, 'call federation_node_drain_queue with arguments {}', directly contradicts the five required parameters in the schema. This is actively misleading: an agent following the description would omit node_id, nonce, timestamp, signature, and alg.

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

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

The opening sentence names a specific operation and resource: collect brokered acts queued for your node. It then sharpens the scope with a construction-level guarantee that a node drains only its own queue, which distinguishes it from other federation node tools without needing to inspect a schema.

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 frames the tool as poll-shaped and notes that the node collects on its own initiative. It also states the authentication precondition ('No operator token; the signature is the auth'). It does not name an alternative to use instead, but it references report-in as a comparable signing pattern and gives enough context for when this call is appropriate.

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

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

Beyond annotations, it discloses side effects (advances the node's liveness clock separately from operator standing), failure behavior (fails closed on bad/absent/replayed signature or stale timestamp), and the auth model (signature is the auth). No contradiction with readOnlyHint=false or idempotentHint=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?

The description is dense but logically organized: purpose, auth, payload, effect, failure mode, and return format. The example 'call federation_node_report_in with arguments {}' is misleading given five required parameters, and 'CO 486' adds jargon. Still, each sentence carries unique 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?

With no output schema, the description fully specifies return values: { ok: true, last_report_in, report_in_count } or { error, code }. It also covers auth requirements, failure cases, and side effects, making it complete for a complex node-reporting operation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the signed envelope { node_id, nonce, timestamp, route } and that the signature is verified against the bound key, tying parameters together. However, it mentions 'route' which is not in the schema, and other parameter details largely restate the schema.

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

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

The description states a specific verb and resource: a self-hosted node reports in to the hub on its own initiative, carrying version, catalog digest, and journal head. It clearly differentiates from sibling federation tools by emphasizing node-signed, node-initiated semantics and the mothership link role.

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 establishes when this tool is for node-initiated reporting and that the hub never calls the node, and clarifies that no operator token is required. It does not name sibling alternatives or state when not to use it, but the node/operator auth distinction provides clear routing 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 declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'public and read-only, no token needed' and 'This tool changes nothing'. It adds substantial context beyond the annotations: pricing model (6%/3%), return document location (identical to /.well-known/comos-vendor.json), and next-step application flow. No contradiction.

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

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

The description runs long for a zero-required-param read tool. Pricing details and OAuth walkthrough could arguably live in federation_apply's documentation, and the 'door's window' metaphor appears twice (title and body). However, each clause does convey information, and the return-shape spec at the end is valuable. It's dense but not bloated — a long paragraph where a few sentences would have sufficed.

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

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

For a simple read-only tool with strong annotations and no output schema, the description is thorough: it discloses the return shape inline ({ offer, how_to_apply }), documents auth requirements (none), notes idempotency, and describes the operational flow. There are no unexplained side effects or missing behavioral surfaces that annotations don't already cover.

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

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

Schema coverage is 100% — the only parameter (channel) is already fully documented in the input schema. The description adds minimal parametric value beyond the example invocation 'call federation_offer with arguments {}', which is a slightly useful illustration but trivial given zero required parameters. Meets the baseline-3 for high coverage.

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

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

Uses a specific verb+resource ('Read the ComOS network's vendor offer') plus scoping constraints ('public and read-only, no token needed'). The title 'The Door's Window' and the explicit contrast with federation_apply ('this tool changes nothing... federation_apply is the door') sharply distinguish it from siblings like federation_apply.

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

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

Explicitly names the alternative tool (federation_apply), describes the full workflow ('obtain an OAuth token... then call federation_apply with it'), and states when no auth is needed. The 'no token needed' line tells agents not to chain an auth step for this particular call — a clear when-to-use signal.

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 graves, idempotent, and non-destructive, but the description goes well beyond by explaining the pricing model dynamics (usage-to-date, tiered curves), the 'reprices are effective-forward' behavior, and the guarantee of consistency with the metering seam. It also clarifies exemptions (lifecycle events, never priced) and failure modes in the return shape. 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 a single focused paragraph that packs a dense amount of meaning into every clause: it states the tool's purpose, the cost model, edge cases (unlisted tools, lifecycle), the existence of repricing (“Reprices are effective-forward”), the consistency guarantee (“the metering seam enforces”), and the return shape. No word is wasted, and it is front-loaded with the core value proposition.

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 this is a read-only pricing tool with no parameters, no output schema, and rich annotations (readOnlyHint, idempotentHint), the description is exemplary. It explains the pricing semantics (usage-tiered curves, free-to-start, steady pricing), what is not priced, how repricing works, and the exact return structure. It even notes the return includes failure modesnewlines and platform definitions, which is more than enough context for the agent to understand when and how to invoke it.

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 there is nothing for the schema to cover beyond the empty properties object. The description confirms no arguments are needed by including 'call federation_pricesheet with arguments {}' as an example. While the baseline for a zero-param tool is 4, the description adds value by explaining what the returned structure will be (a detailed JSON format), making the zero-parameter simplicity explicit.

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

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

The description clearly states the tool's purpose: to read the federation pricesheet, which maps every platform's per-act Com prices. It explicitly specifies the resource (pricesheet) and the scope (all platforms, usage-tiered curves), distinguishing it from siblings like federation_catalog_* by focusing on pricing and lifecycle rules.

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 identifies when to use this tool (to read the current pricesheet) and provides key decision cues: tools not listed are free, lifecycle events are never priced, and the returned structure is described. It also tells the agent that this tool reflects the actual enforcement map, which is a clear reason to call it for pricing 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?

Beyond the annotations (read-only, idempotent, non-destructive), the description adds behavioral details: it is fast and deterministic, returns an empty route with `unroutable:true` when no platform matches, and explicitly states it is not a transaction. This gives agents a clear expectation of side-effect-free behavior and failure handling.

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 highly repetitive, restating the same information multiple times (e.g., the purpose is repeated in various phrasings, the return type is described twice). It also contains a typo ("An intent platform serves returns an empty route") which hampers readability. The core content could be conveyed in a concise paragraph.

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

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

Despite its verbosity, the description covers all critical aspects: input (intent), output (ranked platforms with tools), edge cases (empty route when no platform matches), and behavioral characteristics (fast, deterministic, not a transaction). It also provides an example call. Thus, it is functionally complete for an agent to understand and use the 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 schema already provides descriptions for both `intent` and `limit`. The description adds value by giving concrete examples for `intent` (e.g., "t-shirts", "make an appointment") which clarifies the natural-language input format. However, `limit` is not elaborated beyond its schema text, and the example call uses `{}` without discussing `limit` behavior.

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

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

The description clearly states the tool's purpose: routing a natural-language intent to the right platform on the ComOS network. It gives concrete examples ("t-shirts", "make an appointment") and explicitly clarifies it returns a route, not a transaction, distinguishing it from typical action-oriented 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 explicitly says "the first thing to call," establishing it as the entry point for intent resolution. It also explains that after receiving a route, the caller should act on the chosen platform with the specified tools, providing clear next-step guidance. The example call with `{}` further demonstrates usage.

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 readOnly, idempotent, and non-destructive hints. The description adds valuable context: computed from real GL rows (never asserted), live data, the 'unbalancedEntries' defect even when margin is positive, and the always-free cost. It does not contradict annotations and enhances the behavioral profile with operational 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 information-dense but well-organized: starts with a purpose question, then details the invariants, conditions, posture, cost, and an example. Every sentence adds value, though it could be slightly tightened; it remains readable and front-loaded.

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

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

Despite no output schema, the description explains all major return fields (reserve, outstanding, margin, solvent, unbalancedEntries) and the condition for solvency. It covers cost, read-only nature, and data source (live GL). Missing details on mintCutRevenue and commissionRevenue are minor given they are self-explanatory names. Overall, complete for a parameterless 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 baseline is 4 per criteria. The description confirms no arguments are needed via the example 'call federation_solvency with arguments {}' and describes all return fields, compensating for no output schema. No additional parameter explanation is needed.

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

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

The description clearly states the tool's purpose: checking if the Com float is backed by the dollar ledger's solvency invariant. It specifies the resource (dollar ledger) and the action (returns live solvency metrics), and the question format immediately conveys intent. It distinguishes from siblings by focusing on solvency, not latency or pricing.

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

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

Provides clear context: it's public, read-only, always free, and used for 'checking whether the backing exists is discovery.' It references 'verify, don't trust' posture shared with federation_latency and federation_pricesheet, implying these are alternatives for similar verification tasks, but does not explicitly state when to avoid this tool or when to prefer another.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds valuable context: the return shape ({ tenant: TenantInfo | null, found: boolean }), the null-if-not-found behavior, and an example call, which goes beyond the annotations.

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

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

Three concise sentences: purpose, return type, and example. Every sentence earns its place, with no redundant or filler content.

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

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

For a simple read-only tool with one parameter, the description covers purpose, return shape, null behavior, and example. Annotations cover safety. No output schema is needed since return format is explicitly described. Complete for its complexity.

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

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

The input schema fully describes the single parameter (tenant_id) with 100% coverage. The description adds an example call format but no additional semantic meaning beyond the schema, so 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 gets detailed information about a specific tenant, listing included fields (metadata, description, configuration). This distinguishes it from siblings like federation_list_tenants (which lists all tenants) and federation_delete_tenant (which mutates).

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 the tool is for retrieving detailed info about a single tenant, and provides an example invocation. However, it does not explicitly mention when to use this over alternatives like federation_list_tenants or state exclusion criteria.

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

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

Annotations already declare read-only, idempotent, and non-destructive behaviors. The description adds substantial context beyond annotations: the return object's field names, the caveat about door-state ('open via tokened apply; tokenless never admits'), and the note that the thesis is 'relayable verbatim to the human root.' 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 overlong and contains redundancy, notably repeating 'Returns' twice and listing the thesis fields twice in slightly different words. It is front-loaded with the core purpose, but the verbose marketing-style language could be trimmed. It would benefit from a more concise structure.

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 informational tool with no output schema, the description fully covers what the tool does, what the response contains (thesis object fields), the caveat, and pointers to related tools. It gives the agent enough context to know when and why to call it, and what to expect in return.

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

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

The tool has zero parameters, and the description explicitly confirms this with 'Example: call federation_why with arguments {}.' It also explains what the returned thesis object contains, giving meaning to the call even though no parameters exist. Baseline for 0 params is 4, and the description adds further clarity, justifying a 5.

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 contrasts with federation_help ('tells you HOW; this tells you WHY'), distinguishing it from the closest sibling. The verb 'returns the thesis' and detailed content further specify the resource.

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

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

Provides explicit usage guidance: 'Read this if you (or your human) are deciding whether to invest a few Coms to stand up a business.' It also names the alternative (federation_help) and explains the choice. This tells the agent exactly when to invoke this tool versus others.

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

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

The description reinforces the annotations by explicitly stating read-only behavior and no transaction. It also adds details about being zero-arg and identity-free, providing full transparency about what the tool does and does not do.

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 concise but includes a few extra phrases like 'in the comos-federation voice' and an example call. These add some verbosity but are not excessive, so it remains clear and focused.

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-argument read-only tool, the description is complete: it states what it returns (markdown), that it is read-only, and provides an example. No output schema is needed given the simple nature of the 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 no parameters, and the description explicitly states 'zero-arg', which fully covers the parameter semantics. Schema coverage is complete since there are no parameters to document.

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: reading the 'How to use ComOS' walkthrough knowledge and returning it as markdown. It uses a specific verb (read) and resource (walkthrough knowledge), and it is distinct from sibling tools that perform federation or introspection operations.

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 indicates when to use it (when you need the walkthrough knowledge) and explicitly notes it is read-only and performs no transaction. It does not explicitly compare with alternatives, but the context of sibling tools makes its specific role clear enough.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses the version limitation and the specific behavior for invalid ids (returns uncited(out_of_scope) instead of an error). It also hints at future capabilities. This adds value beyond the annotations without contradicting them.

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 overlong and includes a misleading example: 'call introspection_corpus_compare with arguments {}' suggests calling with no arguments, but the schema requires two required parameters. This could confuse an agent. The version-note and future plans add noise; the key information could be conveyed in two concise sentences.

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

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

Given the simple tool (2 string params, read-only, idempotent) and existing annotations, the description provides essential constraints (valid id, behavior for invalid ids) but leaves out what the 'comparison' result looks like. Since there is no output schema, a brief example or format hint would help, but the description is adequate for a limited 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 schema provides no descriptions and the description does not elaborate on the meaning of corpus_id_a and corpus_id_b beyond calling them 'ids' and stating 'current' is the only valid value. It implies both should be set to 'current', but does not explain what the comparison entails or how the two parameters relate. Since schema coverage is 0%, the description compensates only partially.

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 'Compare two corpora by id' - a specific verb and resource that distinguishes this from sibling tools like introspection_corpus_generate or introspection_corpus_query. It also clarifies the version context and the scope of valid ids, making its purpose unambiguous.

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

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

The description provides explicit usage guidance: only the literal string 'current' is valid, and passing it for both sides is the intended sanity-check usage. It also explains that other ids return uncited(out_of_scope) rather than an error. However, it does not explicitly recommend when to use this tool over alternatives, though the context implicitly frames it as a testing/validation tool.

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

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

Annotations already mark this read-only and non-destructive, and the description adds important behavioral context beyond them: it returns candidates, not verified contradictions, never claims passages contradict, and is a v1 implementation. This prevents the agent from over-interpreting results.

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

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

The description is front-loaded with purpose, then exposes the key caveat and parameter behavior. There is some redundancy in restating that these are candidates 'not detected contradictions' in consecutive sentences, but it is still compact and easy to scan.

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 two-parameter read-only tool with no output schema, this is complete: it covers what is returned, what is not returned, the optional parameter, and demonstrates the required call shape. An agent has enough context to invoke it correctly.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It explains topic as the subject of overlap and repo as an optional restricter of candidates to one repo, and provides a usage example. It could add more detail about how topic is matched, but the essential semantics are present.

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

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

The description names a specific action and resource: ask the corpus for candidate artifacts likely to disagree on a topic. It also states the specific return type (term-overlap candidate artifacts) and explicitly distinguishes it from passage-level disagreement detection, differentiating it from related introspection 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 gives a clear use context (wanting to know where corpus artifacts may disagree on a topic) and an explicit exclusion (passage-level disagreement detection is not implemented). It does not name a specific alternative tool for that excluded case, so it falls short of a full 5.

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

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

The annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds that results are uncited(out_of_scope) when not covered, which is useful behavioral context. It does not detail return format specifics, but with annotations handling the safety profile, 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, with three sentences that front-load the core purpose and then add scope details. It includes a clear example call. It could be slightly more polished by clarifying the example, but it earns its place with no wasted words.

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

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

Given the tool has 2 parameters, no output schema, and moderate annotations (readOnlyHint), the description reasonably covers the inputs and hints at the return type (topical map). It lacks details on the structure of the output or any edge cases, but for a read-only probe tool, it is sufficiently complete, though not exhaustive.

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 'topic' as the subject of the query and 'repo' as a scope limiter, providing meaning beyond the schema. It also gives an example call with '{}', though that example is for no arguments, which is slightly misleading since 'topic' is required. Overall, it adds value for both parameters.

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

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

The description clearly states the tool's purpose: to ask the corpus about its coverage on a topic and return a topical map with citations. It distinguishes itself from sibling tools like introspection_corpus_query by focusing on scope/probe rather than general query, though it doesn't explicitly name the alternative. The verb 'probe' plus resource 'corpus' is specific.

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

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

It provides some context on when to use the tool (when asking what the corpus covers on a topic) and mentions an optional 'repo' parameter to scope the question to one repo. However, it does not explicitly say when not to use this tool or mention alternatives like introspection_corpus_query, leaving the distinction 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 disclose read-only, non-destructive behavior. The description goes beyond them by explaining that cited paths resolve through the pinned manifest and that content excerpts are verified as substrings of the artifact. It also makes the cited versus uncited return distinction clear.

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 short and front-loaded, but it contains a redundant Returns: sentence and an unhelpful or invalid invocation example. Each sentence adds some context, but the structure would benefit from removing the repetition and fixing the example.

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 two-parameter, read-only query tool with no output schema, the description provides essential context: return shape, verification guarantees, repo filtering semantics, and no destructive behavior. It does not explain empty-result behavior or question revision, but those are not necessary for this complexity level.

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 no schema description coverage, the description compensates partially: repo is explained as a filter on manifest entries, and question is clearly the corpus question. However, the example of calling with empty arguments conflicts with the required question parameter, which makes the usage guidance misleading in an important spot.

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 verb and resource: ask the corpus a question. It also gives the result shape with cited or uncited outcomes, which makes its purpose concrete and reasonably distinct from sibling corpus comparison and probing tools, though it does not explicitly name alternatives.

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

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

The description implies the main use case: query the corpus, optionally restricted to a single repository. However, it does not say when to choose this over the sibling introspection corpus tools, nor does it state when this tool should not be used.

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, idempotentHint=true, so the safety profile is covered. The description adds beyond annotations: it explicitly states 'Never silently reconciles drift,' describes the two possible return kinds ({kind: "evidenced", value, chain} or {kind: "no_evidence_available", reason}), and mentions provenance (comai-plan CO 013-003 / federation CO 006). This is valuable context 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 dense but well-structured. It front-loads the main purpose, then details graph components, drift behavior, return contract, provenance, and an example call. Every sentence adds value, though the provenance line and example could be considered non-essential. Slightly verbose but not wasteful.

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 moderate complexity (graph with nodes/edges, drift reports, multiple return kinds), the description is complete. It explains the graph structure, the meaning of drift, the return schema (evidenced/no_evidence), and even provides an example invocation. With no output schema available, the description fully carries the burden of explaining the result shape, and it does so effectively.

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 takes zero parameters, so the schema provides full coverage (100% trivial). The description does not need to explain parameters, and it doesn't. Baseline for 0 parameters is 4, which is appropriate; nothing to add.

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

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

The description clearly states the verb (Return), the resource (dependency graph of change orders), and the scope (across every registered ComOS repo). It then itemizes the graph components (nodes, parent/child edges, interest edges, drift reports) distinguishing it from sibling introspection tools like introspection_system_list_nodes or introspection_system_diff.

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

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

The description implies when to use this tool—whenever you need the full dependency graph of change orders, especially to inspect drift without silent reconciliation—but does not explicitly name alternatives or state when NOT to use it. The 'Never silently reconciles drift' behavior hints at a use case but no direct comparison to other introspection tools.

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

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

The annotations already indicate readOnlyHint, idempotentHint, and non-destructive, so the core safety profile is known. The description adds meaningful behavioral context: it traverses interest and parent/child edges, returns provenance for each artifact, and specifies the evidence chain (D8 seeds-walked). It also discloses the return shape (evidenced vs no_evidence_available). 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 information-dense but somewhat redundant: it repeats the return type and includes an example call that adds little value. The core content is front-loaded with the purpose, and the parameter explanations are adequate, but the example and the final 'Returns' sentence are redundant and could be trimmed.

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 (traversal over graph edges, multiple parameters, evidence chain), the description provides a thorough overview without needing an output schema. It covers purpose, parameters, defaults, traversal behavior, and return types. It doesn't specify edge cases like empty result or unreachable nodes, but the evidence-chain disclosure compensates. Overall, it's nearly complete.

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

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

The schema has 0% coverage, meaning the description must explain the parameters. It does explain origin_slug (CO directory slug, example), max_hops (default 1, bounds depth), and include_parent_child (default true, meaning). However, it doesn't detail max_hops' allowed range or include_parent_child's exact effect on the return beyond 'counts as reach', which leaves room for slight enhancement.

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 returns the REACH of a change, specifying every artifact across every registered repo that declares interest, with traversal over the change-graph's edges. It distinguishes itself from other introspection tools by focusing on the reach (impact) rather than the change itself, and provides a concrete example target.

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 how traversal works (max_hops bounds depth, include_parent_child toggles the decomposition tree) and implies when to use it (to find all surfaces a change reaches). It doesn't explicitly list alternatives or when-not-to-use, but the context signals (sibling tools) provide enough distinction.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it explains the return shapes (ClimbSnapshot[] with chain, or no_evidence_available with reason), and the limits (max 200 snapshots, limit cap 1000). This goes beyond annotations, though it doesn't elaborate on potential performance implications or edge cases (e.g., what happens if since is invalid).

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 front-loads the core behavior, then details the return shapes, then lists parameters, then an example. Every sentence adds value without repetition. It's a single paragraph but logically organized.

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

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

Given the tool's moderate complexity (3 params, no output schema, no nested objects), the description is complete for an agent to invoke it correctly: it covers defaults, limits, param formats, return kinds, and error handling. It even provides an example call. No gaps identified.

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 carries full param burden. It explains all three parameters: since=ISO timestamp, limit=integer ≤1000, repo=string. It also adds context on defaults (window 7 days, max 200 snapshots, default repo) that aren't in the schema. This is excellent compensation for the schema's sparse documentation.

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 is a time-series read of honesty-ratio snapshots for a federation, with a specific verb (read/climb history) and resource (windows of snapshots). It distinguishes from siblings by specifying the introspection_system prefix and contrasting with other introspection tools (e.g., list_nodes, diff) and 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 gives explicit usage context: default window is last 7 days, max 200 snapshots, default repo is 'comai-plan', and it explains when to pass a different repo id. It also specifies when it returns no_evidence_available, which helps the agent decide when to use this tool vs alternatives like list_nodes or list_repos.

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 establish the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavior beyond that: it describes the two possible return shapes ({kind: "evidenced", value, chain} or {kind: "no_evidence_available", reason}) and notes the inclusion of confidence, threshold, outcome, accountability, and PR links. 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 dense and front-loaded with purpose and modes, but it is a long single block with redundant return statements ('Returns: The recorded change-order decisions' repeats earlier content) and a placeholder example that uses "<mode>" rather than a concrete value. It could be tightened 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?

For a read-only query tool with no output schema, the description covers the essential context: all three modes, associated parameters, return envelope variants, and provenance note. Minor gaps remain, such as what happens if both co_id and agent_id are supplied or whether mode values constrain required parameters, but overall the tool is well-specified.

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

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

Schema coverage is 0%, so the description must compensate—and it does. It explains when to supply co_id versus agent_id and maps each mode to the relevant parameter. The schema only lists the enum and maxLength, so the description adds meaningful usage semantics beyond the structured fields.

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 explicitly states the tool 'Query the CO-management decision log' and details what it returns: every change-order operation an agent scored or actuated. It clearly distinguishes itself from sibling tools by naming the specific domain (CO-management) and the three query modes.

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?

Usage context is clearly given through mode-specific instructions: mode="touched_co" with co_id, mode="agent_autonomous" with agent_id, mode="escalated" for waiting items. It does not explicitly state when not to use the tool or name alternatives, but the mode examples provide clear situational 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 and idempotent, so the description need not repeat that. The description adds that it returns an evidence chain and that it may produce 'no_evidence_available', which provides transparency about outcomes. However, it doesn't detail any system behavior beyond that, such as potential errors or response format nuances.

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 with approximately four sentences, front-loaded with the purpose and key parameters. It includes an example call, but the final sentence about 'Returns: Confidence metrics...' is somewhat redundant and could be trimmed for better 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?

The description covers the main purpose and response shape, but given the complexity of federation contexts and the lack of an output schema, it could clarify edge cases like when 'no_evidence_available' occurs or how the chain is structured. It also references 'Phase A' without explaining it, leaving some ambiguity for new agents.

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

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

With 0% schema description coverage, the description must compensate. It explains node_kind enum values (artifact | tool | tenant) and node_id semantics (path | name | id), and mentions optional repo for scoping. However, it does not fully elaborate on each parameter's constraints or how they interact, especially the repo and node_id 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?

The description clearly states the tool returns a confidence number for a federation node, specifying the node_kind types. It distinguishes itself from siblings like introspection_system_list_nodes by referencing it as the source of valid node ids, but does not explicitly contrast with other introspection 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 implies usage for querying confidence on nodes, but does not explicitly state when to use this tool vs others like introspection_system_probe or introspection_system_change_graph. It mentions 'repo' scoping for Phase A but lacks clear exclusions or alternatives.

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

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

The description adds meaningful behavioral detail beyond the annotations: limit truncates returned rows while the summary still reflects the full set, and the tool can return either evidenced gaps or a no_evidence_available reason. These details are useful because they describe edge behavior that an agent could not infer from the idempotent/read-only annotations alone.

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 purpose and usage guidance are front-loaded, but the description is somewhat redundant: the summary behavior is described twice, once in the first Returns sentence and again in the second Returns sentence. The example at the end is a placeholder that adds little value beyond restating the tool name.

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

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

The description covers return shapes, the no-evidence branch, and the limit/summary interaction, which is good given there is no output schema. However, the repo parameter is unexplained, and the Gap type and chain field are not described. For a 4-parameter tool with no output schema, this is adequate but not fully 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 compensate for the parameters. It explains scope_kind, scope_id's conditional requirement, and limit's truncation behavior, but it completely omits the repo parameter, which is present in the schema with a min/max length but no semantic context. This leaves a notable gap in parameter understanding.

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 and resource: 'Enumerate structural coverage gaps' and gives concrete categories ('silent tools, artifacts with no eval, un-probed tenants'). It does not explicitly differentiate from the many introspection_system_* siblings, but the purpose is clear enough for an agent to distinguish it from more general probing or query 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 gives clear operational guidance on scope_kind and the conditional requirement for scope_id, and it explains the effect of limit. However, it does not state when this tool should be preferred over related siblings like introspection_system_probe or introspection_system_list_nodes, so the when-to-use-versus-alternatives guidance is missing.

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, covering the safety profile. The description adds that the tool returns 'the structural difference between the two states,' but does not elaborate on how the baseline is interpreted, timezone handling, or any edge-case behavior beyond what annotations already convey.

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

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

The description is short and front-loaded, but the 'Example: call introspection_system_diff with arguments {}' is both incorrect and unhelpful, making the reader doubt the required arguments. The phrase 'same as confidence' is also cryptic for an agent that may not have that sibling's description loaded.

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

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

There is no output schema, so the description should explain what 'structural difference' concretely means; it does not. It also omits how baseline_kind='since' interacts with the baseline date and does not clarify when this tool should be chosen over similar introspection_system_* diff-like 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?

With 0% schema description coverage, the description carries the full burden. It does mention all four parameters, adds 'node_kind/node_id same as confidence', points to list_nodes as the source of valid ids, and gives the baseline date format. However, the semantics are mostly cross-references and format reminders, not deep explanation, and the example with '{}' conflicts with the schema's required 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 opening sentence 'Compare a node's evidence against a baseline date' names a specific verb, a clear resource ('node's evidence'), and the comparison scope. It is distinguishable from siblings by the baseline-diff semantics, though it does not explicitly name alternatives or explain how it differs from tools like introspection_system_change_graph.

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

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

The description provides useful context: node ids come from introspection_system_list_nodes, node_kind/node_id follow the confidence tool convention, and the baseline format is spelled out. However, it gives no explicit when-to-use/when-not-to-use guidance versus similar introspection tools, and the example 'call introspection_system_diff with arguments {}' is misleading given the four required parameters.

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 non-destructive; description adds valuable detail on output shape, activation states, and no-evidence fallback. No contradictions.

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

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

Generally well-organized but contains redundant elements ('Returns: The set of structure-graph nodes' repeats earlier content) and a historical reference (change-order) that adds no operational 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?

Covers all aspects for a read-only enumeration: purpose, output shape, success/failure cases, and optional parameter. Slight ambiguity with 'Phase A' but overall 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?

Only parameter 'repo' is described with semantic meaning ('scopes the artifact list to one repo'), compensating for 0% schema coverage. Adds functional context beyond the bare string type.

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?

Explicit verb 'enumerate' with specific resources (artifacts, tools, tenants) and clear purpose (render picker UIs). Distinguishes from sibling tools like introspection_system_list_repos by scope and output.

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?

Clearly implies usage for picker UI rendering and explains optional repo scoping. Missing explicit exclusions or alternative tool comparisons, but context is sufficient for typical 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?

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description reveals the full return shape, clarifies the semantic guarantee that all returned repos are 'currently active in the federation registry,' and provides the change-order governance context. With no output schema present, this additional return-structure disclosure is highly valuable and goes beyond what annotations capture.

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

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

The description is front-loaded with a clean purpose statement but contains redundancy: 'Returns: The set of covered repositories.' repeats the earlier return-shape mention. The example 'call introspection_system_list_repos with arguments {}' is trivially unhelpful, and 'Added by change-order 2026-05-28-003 (Phase 3)' is process noise that dilutes signal, making it slightly less crisp than it could be.

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 discovery tool with strong annotations, the description is complete: it states what it returns, provides the return structure, highlights the active-registry constraint (a key semantic), and explains how the output should be used. With such low complexity, nothing essential is missing.

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

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

The tool has zero parameters and schema coverage is trivially 100%. The description correctly includes an example call with empty arguments, matching the baseline of 4 for parameter-less tools. No parameter-specific insight is needed since none exist.

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

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

'List the ComOS repositories that contribute to introspection' uses a specific verb+resource combination and names the domain (ComOS, introspection). It distinguishes itself from sibling introspection_* tools by explicitly scoping to repositories and positioning itself as a discovery tool for 'introspection_system_climb_history'.

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

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

It gives explicit when-to-use guidance: 'Use this to discover which repo ids to pass to introspection_system_climb_history.' This clearly states the primary consumer of the output and when an agent should call this tool. It lacks an explicit when-not or alternatives list, but the named downstream tool provides strong 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 read-only and idempotent behavior, and the description adds that the response carries node-specific evidence rather than a collapsed number, clarifying the output format. No contradiction with annotations, and given the read-only nature, side effects are not a concern.

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 succinct, containing a clear purpose, an explanation of the difference from confidence, and an example invocation. No unnecessary words or redundant details.

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

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

The description includes an example call, references to related tools for argument sourcing, and specifies the return content, providing enough context for an agent to invoke the tool correctly. The mention of 'Phase A' also sets expectations about 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 schema defines node_kind, node_id, and optional repo. The description adds meaning by stating that repo scopes to one repo and that valid node ids come from a list function, but it does not individually elaborate on node_kind values, relying instead on the enum and the 'same argument shape as confidence' note.

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

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

The description clearly states that the tool returns the full evidence trace for a single federation node, and distinguishes it from confidence by contrasting 'full evidence trace' with a 'collapsed number'. It also notes the argument shape similarity, giving a precise 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 provides usage context by pointing to introspection_system_list_nodes for valid node ids and explains that the optional repo scopes to one repo (Phase A). However, it does not explicitly list alternatives or when to avoid this tool, though the implication of a detailed counterpart to confidence is present.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it is 'public and read-only; discloses, does not gate,' reinforcing the safety profile and adding the nuance that it does not gate access. It also mentions the return format (raw markdown) and the CO 311 reference, which adds context 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, front-loaded with the purpose, and every sentence adds value: it lists the documents, explains the context, states the argument, and provides an 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 simple read-only tool with one parameter and full schema coverage, the description is complete. It covers what the tool does, the argument values, the return format, and the context. No output schema is needed, and the description does not need to explain return values beyond stating it returns raw markdown.

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 provides 100% coverage with a clear description and enum for the single parameter. The description adds the exact allowed values and an example call, which is helpful but not strictly necessary given the schema's completeness. The baseline is 3, and the example and explicit enumeration push it to 4.

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

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

The description clearly states the tool fetches a ComOS legal instrument as raw markdown, listing the four specific document types. It distinguishes itself from siblings by emphasizing it is public, read-only, and discloses terms, which is unique among the federation and introspection 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 clear context on when to use it: to read legal terms an agent operates under, analogous to reading a pricesheet. It does not explicitly name alternative tools for legal documents, but the context is sufficient given the sibling list contains no other legal-specific tools.

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

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

The description confirms the read-only nature (read-only, no claim required) and matches the annotations (readOnlyHint, idempotentHint, etc.). It also describes the return structure ({ target, count, posts | comments }), providing transparency beyond the annotations.

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

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

The description is well-structured, starting with the tool's purpose, then usage guidelines, and finally return format. It is concise yet informative, avoiding unnecessary verbosity while covering all essential aspects.

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

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

For a read tool, the description fully covers what it does, how to use it, and what it returns. It does not need to elaborate on error handling or side effects since it's read-only and the annotation already covers that. It is complete given the tool's simplicity.

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

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

The description adds semantic value to the schema by explaining the meaning of 'target' values and their dependencies (e.g., 'submolt' required for target=submolt), and clarifies the sort options for feed and comments. This goes beyond the schema's basic 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 reads Moltbook, a social network for AI agents, and clarifies the three target types (feed, submolt, comments) with specific parameters. It distinguishes from sibling tools like moltbook_post by focusing on reading only.

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

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

Explicit usage instructions are provided: 'Use it to listen before you contribute' and detailed guidance on target selection (feed, submolt, comments) with required parameters (submolt, post_id). It also notes the tool is read-only and requires no claim, aligning with the intended use case.

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