ComOS Federation

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

With annotations already declaring readOnlyHint and destructiveHint, the description adds context by specifying 'returns composed knowledge' and 'performs no transaction.' This provides extra insight into the output nature beyond what annotations convey. No contradiction found.

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 concise sentences deliver the purpose and behavioral nuance with no fluff. The structure is front-loaded and every word adds value.

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

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

For a zero-parameter, read-only knowledge tool without an output schema, the description is sufficiently complete. It specifies the resource, the voice, read-only nature, and the composed knowledge output, leaving no critical gaps for an agent to misuse 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 the schema is trivially covered. The description does not need to add parameter detail, and the baseline of 4 applies. It adds no conflicting parameter information.

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

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

The description clearly states a specific verb ('Read') and resource ('About ComOS — the Federation User Manual's knowledge'), adding the voice and read-only nature. It distinguishes itself from general help tools like federation_help by specifying it returns the ComOS knowledge in the comos-federation voice.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives such as federation_help or how_to_about. It does not state exclusions or conditions for use, leaving the agent to infer its applicability from the name and description alone.

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=false, destructiveHint=true), the description adds critical behavioral context: identity spoofing ('from your own address'), caller restrictions, rate limits, journaling behavior ('receipt IS the state delta'), and applicable policy (CO 245). This provides a rich understanding of side effects and constraints.

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

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

The description is slightly dense but every sentence carries unique information: purpose, identity, restrictions, limits, journaling, and policy. It is front-loaded with the core purpose and then details constraints. No fluff, though a few items (plain-text body, no attachments) duplicate schema info.

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 email tool with no output schema, the description fully covers the behavioral contract: who can call, what limits apply, what side effects occur (journaled receipt), and the policy context. It explains the aftermath of a send, which is essential for an agent to reason about state changes.

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 parameters are already well-documented. The description adds meaningful semantics: body must be ≤2000 chars plain text, no attachments, and 'to' must be a real counterparty, never invented. This clarifies the intent and constraints 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 action ('Send one outbound email'), specifies the resource (email as a CO 230 cohort agent), and distinguishes itself as 'the rail for contacting a REAL external counterparty'. This differentiates it from sibling tools like moltbook_post or federation_run_agent.

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 identifies when the tool should be used: for contacting a real external counterparty (vetted provider or prospect). It also states clear exclusions (restricted to cohort roots ent-001..005, any other caller denied) and hard limits (5 sends/agent/day, body size, no attachments). It does not name specific alternative tools, but the context is strong enough to guide selection.

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

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

The description adds significant behavioral context beyond the annotations: the verdict is recorded with attribution, preserves the gate's original reasoning, affects all tenants' reputation, and self-admission is forbidden. These details align with destructiveHint=true and disclose consequences.

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

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

The description is compact and front-loaded with the primary purpose, then adds necessary cautions and behavioral details. Every sentence contributes value without redundancy.

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

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

The description covers permissions, side effects, attribution, and reasoning requirements, which is complete for a decision tool with no output schema. It does not explicitly state return values or error behavior, but for this action type the description is sufficient.

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

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

Schema coverage is 100% and the description does not introduce substantial per-parameter syntax beyond what the schema already provides. It adds semantic context about attribution and reasoning, but parameters like platform and tenant_id are already fully described in the schema.

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

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

The description uses a specific verb ('Render the operator verdict') and identifies the exact resource ('under-review admittance application (CO 344)') with clear actions ('admit or exclude'). This clearly distinguishes it from sibling tools like federation_admittance_queue or 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?

The description states when it applies (under-review applications) and gives critical usage constraints: FEDERATION ROOT MANAGER ONLY, manager cannot admit itself, and the platform-wide impact of admission. It does not explicitly name alternative tools but the context is sufficient.

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

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

The description adds important behavioral context beyond the annotations: returns oldest-first, warns about checking the 'truncated' flag to avoid misreading an empty queue, and specifies the 'managers:admin' permission requirement. This is valuable operational detail.

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: the first states the core function, the second describes ordering behavior, and the third is a critical safety warning plus auth note. Every sentence earns its place with 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 simple read-only tool with one parameter, the description covers purpose, ordering, safety caveat (truncated), and permission context. The annotations already declare read-only, and no output schema is needed to convey return value expectations.

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 the single 'platform' parameter with a description and 100% coverage. The tool description does not add any new information about the parameter, so it meets the baseline for high 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 states 'Read the applications awaiting an operator decision on a platform' using a specific verb and resource, which sets it apart from the sibling 'federation_admittance_decide' tool. It also mentions the specific behavior of returning oldest-first, further clarifying its 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?

The description implies its use as a read-only precursor to decision-making, especially with the sibling 'decide' tool. It does not explicitly name alternatives or exclusions, but the context of reading applications for operator decisions is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, which cover the safety profile. The description adds context about authentication (JWT, agents:read scope) but does not disclose what 'status' includes, response format, or any behavioral traits beyond the annotations. This is adequate but not rich.

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

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

The description is concise and front-loaded with the purpose. However, the final sentence about 'agentId comes from federation_list_agents' is extraneous and irrelevant since no agentId is used, making the description longer than necessary and somewhat confusing.

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 the core purpose, authentication, and required scope. Yet it omits any details about the returned status data (e.g., format, fields, meaning of statuses) and includes an irrelevant agentId reference, leaving gaps in completeness, especially since there is no output schema.

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

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

The schema already describes auth_token as 'JWT auth token for authentication', and the description enriches it by specifying it is a federation OAuth access token requiring agents:read scope. This adds meaningful context beyond the schema's simple description, though there is only one parameter.

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

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

The first sentence 'Get current status of all agents and the scheduler' clearly states the tool's purpose with a specific verb and resource. However, the additional mention of 'agentId comes from federation_list_agents' is confusing because no agentId parameter exists in the schema, which slightly muddies the purpose.

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

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

The description provides prerequisites (auth_token, agents:read scope) and references a related tool (federation_list_agents) but offers no explicit guidance on when to use this tool versus alternatives, nor any exclusions. Usage context is only implied through the authentication requirements.

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 goes far beyond the minimal readOnlyHint/destructiveHint annotations. It details side effects: minting a manager root, binding to the token's email, no human review, no charge, fee structure, and governance implications. This fully discloses the behavioral impact of the call.

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 primary purpose and then packs each sentence with relevant details: token behavior, offer references, fees, and governance. There is no filler; every sentence contributes useful, non-redundant information.

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

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

For a complex tool (network admission with legal and financial implications), the description covers purpose, process, fees, governance, and token semantics. It does not discuss return values, but the absence of an output schema reduces that burden. The description is sufficiently complete for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, and the schema already provides good parameter descriptions. The description adds crucial semantic meaning, especially for 'email' (root bound to token email vs. contact metadata) and 'applicant_name' (manager/venture name). This complements the schema well, though it does not elaborate on every parameter.

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

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

The description opens with a specific verb+resource: 'Join the ComOS network as a vendor.' It clearly explains the two modes (with/without token) and what the tool accomplishes (admittance or contact request). It distinguishes itself from siblings like federation_admittance_decide by positioning itself as 'The Door' for vendor admission.

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 strong context on when to use the tool: to join as a vendor, with or without an OAuth token. It clearly explains the token vs. tokenless behavior. However, it does not explicitly name alternative tools or state when to prefer them, so it stops short of full 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 and destructiveHint=false. The description adds valuable context about the metric: it is a 'trust-weighted function of real settled transactions, not raw volume,' derived from 'ComOS-signed counters (CO 200),' and presented as 'a fact surfaced, not a verdict rendered.' This goes 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?

Three sentences, front-loaded with the core concept, then usage and relationship. Every sentence adds distinct information: what the arena is, how to invoke it with different args, and how the ranking metric is derived. There is no filler.

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

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

For a read-only tool with no output schema, the description covers the purpose, the ranking metric, parameter behavior, and the relationship to sibling catalog tools. It does not explicitly describe the return structure, but the context is sufficient for an agent to decide when to use it and what arguments to pass.

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

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

Schema description coverage is 100%, with detailed descriptions for limit, platform, and tenant_id (including default, max, and effect on rank). The description reinforces these with usage hints but does not add significant new meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool ranks agent-run businesses by 'settlement-signed reputation' and explicitly distinguishes it from siblings: 'the catalog is how you enter; the arena is how you're ranked.' It is a specific verb+resource ('ranked businesses') that differentiates from the catalog tools.

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

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

The description gives explicit usage patterns: 'Omit args for the top of the board; platform= to filter by vendor type; tenant_id= for one business's rank.' It also names the alternative catalog tools and clarifies their relationship, effectively telling the agent when to use this tool versus them.

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

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

The description discloses a significant side effect: attesting can lift a mandate-decayed root within ~30s, which is a state change. However, the annotations declare readOnlyHint=true, directly contradicting this behavioral disclosure. This is an annotation contradiction.

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

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

Four dense sentences cover purpose, implicit behavior, usage timing, self-healing effects, exclusions, and timing. Every sentence contributes essential information with no filler.

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

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

Despite lacking an output schema, the description fully equips the agent to decide when and why to invoke the tool, what to expect after invoking, and important exclusions. It is self-sufficient for a zero-parameter tool.

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

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

With zero parameters, the description still adds value by explaining that identity is read from the token, clarifying why no parameters are needed and preempting potential confusion about authentication.

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 'attest' and resource ('manager root is alive'), tied to a specific mandate (CO 264). It distinguishes this from sibling tools by explaining it is a liveness attestation rather than administrative freeze/unfreeze actions.

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 says when to call: when idle or to self-heal a mandate-decayed root. It also provides a when-not: every privileged action already attests implicitly, and explicit operator freezes are NOT lifted. This gives clear usage boundaries.

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

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

The description discloses key behavioral aspects not covered by annotations: the state transition from spendable to bonded, accumulation on existing bonds, the OAuth scope requirement ('tenants:write on your federation OAuth bearer'), and the release clock/active standing condition. Annotations are only simple hints, so the description carries the full burden and does so thoroughly without contradiction.

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

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

The description is multi-sentence but every sentence earns its place: it states the core action, the ledger effect, the published status, the release/standing caveat, the optionality, and the auth requirement. It is front-loaded with the primary function and avoids unnecessary filler. The moderate length is justified by the tool's complexity.

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

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

With no output schema, the description could ideally state the return value, but it thoroughly explains the effect, the auth requirement, the accumulation behavior, and the relationship to the release clock and status tool. This is sufficient for an agent to select and invoke correctly. The slight gap is the lack of explicit response/error expectations, but it is minor given the rich context.

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

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

Schema description coverage is 100% and both parameters have clear descriptions (amount as 'positive integer' that 'accumulates', tenant_id as 'a tenant your root owns'). The description reinforces tenant ownership ('treasury you OWN') but does not add meaningful parameter-level detail beyond what the schema already provides. 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 opens with a specific verb+resource: 'Post (or increase) your manager root's bond (CO 265)' and explains the exact action (moves funds from spendable to bonded). It clearly differentiates from siblings by naming federation_bond_status and describing release behavior, making it obvious this tool posts/increases a bond rather than checking or releasing it.

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

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

The description provides context for when this tool is relevant: 'Optional, never required at the door' and explains the release clock/standing requirement that depends on the bond. It points to federation_bond_status for weighing the bond, implying alternative usage. However, it does not explicitly say 'use federation_bond_release to release' or lay out direct when-to-use vs alternatives in a structured way.

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=false, destructiveHint=false), the description discloses a two-step process, the notice clock, the restart condition, the absence of forfeit/reviewer, and the consequence of illiquidity. It also clarifies the auth scope, adding significant behavioral context.

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

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

The description is compact yet information-dense, with each sentence earning its place. It front-loads the core action, then explains the two-step process, conditions, consequences, and auth—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's complexity (two-step process, conditional completion, edge cases) and the absence of an output schema, the description covers all essential context: how to invoke, prerequisites, behavioral nuances, consequences, and expected outcomes. It is complete for an agent to use correctly.

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

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

The tool has zero parameters and schema coverage is 100%, which sets a baseline of 4. Since there are no parameters, the description does not need to provide parameter-level detail, and it doesn't.

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

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

The description clearly states the action 'Release your bond (CO 265)' with a specific verb and resource, distinguishing it from related tools like federation_bond_post and federation_bond_status. It also references the legal code, making the purpose unambiguous.

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

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

Provides explicit usage steps: 'First call starts the notice clock... call again at maturity to complete'. It also states required conditions (standing ACTIVE) and an exclusion ('any explicit standing transition restarts the clock'), plus the auth requirement. This gives the agent clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds context about the public, machine-legible nature and the specific fields returned, which goes beyond the safety hints and helps the agent understand output. No contradictions 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 only two sentences, front-loaded with the verb and resource, and every phrase adds value (scope, fields, default behavior). No wasted words or redundancy.

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

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

For a simple read tool with one optional parameter and no output schema, the description adequately conveys what is returned (amount, state, notice maturity) and the default behavior. It does not explain error cases or the meaning of 'standing-fact block named', but these are minor omissions given the tool's low 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 schema already provides a clear description for the single manager_id parameter ('defaults to the caller'). The tool description repeats this instruction ('Omit manager_id to read your own'), adding no new semantic detail. With 100% schema coverage, the description does not compensate further.

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

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

The description uses the verb 'Read' and names the specific resource 'manager root's bond', enumerating the returned fields (amount, state, notice maturity). This clearly distinguishes it from sibling write tools like federation_bond_post and federation_bond_release, and the 'public machine-legible fact (CO 265)' provides domain context.

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 clear context for when to use this tool (reading bond facts) and instructs to omit manager_id for the caller's own bond, which is a useful usage guideline. It does not explicitly name alternatives or exclusions, but the read vs. write distinction is implied by the verb and sibling names.

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

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description reveals that the response includes a 'source' field indicating whether the store row or compiled fixture seed answered, and requires managers:admin permission. This adds meaningful behavioral context beyond what structured annotations provide.

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

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

The description is two sentences that are information-dense without filler. Each clause adds value: the raw canon vs flattened distinction, the source field behavior, the put precondition, and the permission requirement.

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 partially explains the return via 'source' and the document set, but does not fully specify the response structure. However, for a read operation with one parameter and simple semantics, the description is sufficiently complete for most agent use cases.

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

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

The input schema already fully describes tenant_id with an example, so description need not add much. The description does contextualize the parameter by tying it to the tenant's raw canon, but otherwise does not add syntax or format details 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 reads a tenant's RAW knowledge canon from a specific store, distinguishing it from the flattened markdown served by another tool and from federation_canon_put which it complements. The verb 'Read' and resource 'tenant's RAW knowledge canon' are explicit and 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 clear context by contrasting with the flattened markdown served by the composed knowledge tool and mentions that federation_canon_put refuses until the store row exists, implying when to use this read to verify raw canon. It does not explicitly name a when-not-to-use scenario, but the distinction is strong enough for an agent to select appropriately.

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 (destructiveHint=true, readOnlyHint=false), the description adds rich behavioral context: edits existing rows only, refuses empty sets, immediate effect ('next request serves the new text'), auth required, and fixture warning. 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 long but dense, with every sentence carrying important warnings or scoping details for a destructive operation. It is front-loaded with the core purpose and uses emphasis (bold/uppercase) effectively. Slightly verbose but justified.

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 purpose, scope, constraints, auth, timing, and persistence caveat. With no output schema, it could mention the return value or error handling, but overall it is complete for a destructive write tool. The complexity is high, so this level of detail is appropriate.

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

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

Schema coverage is 100%, but the description adds meaningful extra semantics: 'confirm must exactly equal tenant_id', documents are the FULL replacement set, and empty document set refused. The label parameter is not expanded, but the schema already explains it. Adds value beyond 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?

The description opens with 'Replace a tenant's knowledge canon' – a specific verb and resource. It further clarifies 'WHOLE-CANON REPLACE' and 'front-door write surface', which clearly distinguishes this from read or update siblings like federation_canon_get or federation_update_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?

Gives explicit when-to-use guidance: 'send every document, not a delta', 'boot seed owns creation' (so not for creation), and 'empty document set is refused'. Also states the auth requirement (managers:admin) and warns about the fixture seed. Clear exclusions and 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 mark read-only/non-destructive. The description adds that omitting args returns the fleet grouped by who-it-serves and by platform, and that agent=<slug> returns a 'full card' – useful output-shape context beyond the safe-read 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 compact sentences with front-loaded purpose. Every clause adds value: browse action, what it returns, grouping/filter usage, and the pairing with federation_catalog_platforms. 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 read-only catalog with optional filters and no output schema, the description covers all usage modes and sketches the return shape (grouped fleet, full card). The sibling pairing provides enough orientation for an agent to choose appropriately.

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 provides full descriptions for all 3 parameters (100% coverage). The description merely restates the filtering/slug patterns already in the schema (pass serves= or platform=, agent=<slug>), adding no new parameter-level detail beyond what the schema already gives.

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

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

Specific verb 'Browse' + resource 'agent fleet' + scope ('what each agent does and who it serves'). Explicitly contrasts with federation_catalog_platforms ('agents are the operators... platforms are what you become'), differentiating from a key sibling.

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?

Gives explicit invocation patterns: omit args for the grouped fleet, pass serves= or platform= to filter, and agent=<slug> for a single agent's full card. Names a complementary alternative (federation_catalog_platforms) but does not explicitly say when not to use this tool versus other similar siblings like federation_list_agents or federation_agent_status.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, which covers the safety profile. The description adds behavioral nuance: the same call works recursively at every depth and output entries include label, posture, availability, replacement, and tagline. This goes beyond the annotation-provided safety info, though it doesn't describe error handling or pagination.

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

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

Although longer than a simple one-liner, it is dense with useful info and every sentence serves a purpose. The first sentence states the core action and resource, then filters, recursion, output contents, and relationship to sibling tool are covered without fluff. It is front-loaded and appropriately sized for the tool's complexity.

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

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

Given the moderate complexity (recursive catalog, two optional filters) and that there is no output schema, the description adequately explains return values ('Each entry carries label, posture (side), availability, what it replaces, and a tagline') and the tool's role in the ecosystem. It is complete enough for an agent to invoke correctly without further info.

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 provides 100% parameter coverage with descriptions for side and parent, so baseline is 3. The description enriches these semantics with real-world meaning: 'SELL ON' vs 'RUN WITH' for side, and a concrete example ('parent="messaging" returns its channels email, sms, dm'). It also notes that when parent is present, side is ignored, which is also in the schema but reinforced.

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

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

The description opens with a specific verb+resource ('Browse the ComOS network's composable platforms as a recursive catalog') and immediately distinguishes from the sibling federation_catalog_agents by explaining platforms vs agents. It also clarifies the side filter (vendor vs customer), making the tool's function unmistakable.

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

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

It provides explicit usage instructions: 'side="vendor" returns the platforms you can SELL ON... side="customer" returns the tools you RUN WITH... omit side for all' and 'parent="<key>" descends into a platform's sub-catalog'. It also distinguishes when to use this tool versus federation_catalog_agents, giving clear alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context beyond that: it explains the grouping behavior ('collapses size/color variants into one row per product family with a price range and option breakdown'), mentions parallel execution across tenants, and explicitly states 'Public read — auth_token is optional.' 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?

Three concise, front-loaded sentences. Each sentence earns its place: the first defines the core purpose, the second adds the discovery use case and outcome, the third covers the alternative, source of tenant_ids, and auth. No fluff or redundancy.

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

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

For a search tool with good annotations and no output schema, the description adequately explains what the user gets (grouped families with price range and option breakdown), how to scope it (tenant_ids), and auth. It covers parallel execution and the alternative tool. No missing critical context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a bit of semantic context (e.g., tenant_ids source, 'all' option) but mostly repeats what the schema already documents. It does not clarify parameters like limit, category, or query beyond the schema, but it doesn't need to since the schema is thorough.

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

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

The description states a specific action: 'Search product FAMILIES (variants of the same product grouped together) across multiple tenants in parallel.' It clearly distinguishes from sibling tools by naming the exact use case for the alternative: 'Use federation_catalog_search_multi when you need exact variant SKUs.'

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

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

Explicit guidance is provided: 'Prefer this for discovery' and 'Use federation_catalog_search_multi when you need exact variant SKUs.' It also tells where tenant_ids come from ('federation_list_tenants (or pass "all")') and notes auth is optional, giving clear when-to-use 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context: it's a public read with optional auth_token, executes 'in parallel' across tenants, and returns flat results. This goes beyond the annotations and helps the agent understand side effects and security requirements.

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

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

Two sentences, front-loaded with the primary action, followed by targeted usage guidance. Every sentence adds value—no fluff. The sibling tool reference and tenant source tip are tightly packed without redundancy.

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

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

Despite lacking an output schema, the description conveys essential context: what the tool does, how to invoke it, where parameters come from, and when to use the alternative. The parallel execution and flat-result hint compensate for missing return-value schema, making it complete for an agent to select and use correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by noting tenant_ids come from federation_list_tenants and explaining the 'all' option, which is not fully covered by the schema. It also clarifies the output shape ('one row per variant'), enriching parameter understanding beyond the schema.

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

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

The description clearly states the tool's function: 'Search products (flat — one row per variant) across multiple tenants in parallel.' It uses a specific verb (Search) and resource (products across tenants), and distinguishes from the sibling federation_catalog_search_grouped_multi by explicitly contrasting the flat vs grouped result formats.

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 when-to-use guidance is provided: 'Use federation_catalog_search_grouped_multi for browse/discovery flows to get token-efficient family rollups.' It also tells users where tenant_ids come from ('federation_list_tenants') and the special 'all' value, giving clear context and an alternative.

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

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

Annotations already mark it as read-only and non-destructive. The description adds valuable behavioral context: it's a cheap operation, the version is a fingerprint, and it explains consequences of ignoring a changed version (referencing obsolete SKUs). This goes well beyond the annotation hints.

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 clause adds value—covering what it does, how to use the result, and what to do if the catalog changed. No unnecessary words; it earns its length.

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

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

For a simple tool with one parameter, no output schema, and annotations present, the description fully covers purpose, usage, expected behavior, and downstream implications. It is complete and self-contained.

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

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

Schema coverage is 100%: tenant_id is described as 'Tenant ID to get the catalog version for.' The description reinforces the tenant context but adds no new parameter-level details. Baseline of 3 is appropriate given the schema fully documents the parameter.

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

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

The description clearly states the tool's function: 'Return a fingerprint of the current catalog for a tenant.' It specifies the action (return), the resource (fingerprint of catalog), and the scope (for a tenant). It distinguishes itself from sibling catalog_search tools by emphasizing it's a cheap freshness check, not a full search.

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

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

The description provides explicit usage guidance: compare the returned catalog_version to the one from a previous catalog_search, and if they differ, re-run catalog_search before acting (e.g., order_create). It names the alternative tool (catalog_search) and gives a clear when-to-use/when-to-act scenario.

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=true, destructiveHint=false), the description discloses key behavioral traits: constraints 'ELIMINATES non-qualifying tenants,' ranking is 'FACT-ONLY organic_rank,' promotion is a 'SEPARATE, disclosed label slot' and 'never a rank input,' and an 'eliminated' block shows exactly 'who was dropped and on which clause.' This gives the agent a precise model of tool behavior without contradiction.

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

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

The description is dense but well-structured: it leads with the core purpose, then the expected inputs, then the output shape, and finally the usage context. Each sentence contributes distinct information (inputs, constraints semantics, candidates modes, returns, usage context). While longer than the two-sentence ideal, there is no redundant or filler text.

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

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

For a tool with no output schema, the description provides a thorough account of return values: qualifying candidates with aligned facts, an organic_rank, a separate promotion label slot, and an eliminated block. Combined with the input semantics and usage guidance, the description is complete enough for an agent to select and invoke the tool correctly.

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

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

The input schema already provides descriptions for all four parameters (100% coverage). The description adds valuable semantics beyond the schema: explicit examples for `constraints` (e.g., {dimension:'geo',op:'includes',value:'NG'}) and clarifies the two valid forms of `candidates` ({tenant_ids} vs {discover:true,vertical}). This enhances baseline understanding, though `need` and `limit` are not further elaborated.

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

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

The description opens with a specific verb+resource combination: 'Compare federation tenants on their structured choice_profiles to pick one for a need.' It clearly distinguishes from siblings like federation_choice_get (which likely retrieves a single profile) and catalog search tools by focusing on comparison and selection. The mention of 'structured choice_profiles' and 'pick one for a need' shows a distinct 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 concrete usage guidance: 'Use this to choose a tenant before buying via the catalog/order path' and explains the two modes for the `candidates` parameter (search-then-compare vs. discover). It also warns that promotion is 'never a rank input,' preventing misuse with promotion tools. However, it does not explicitly name sibling alternatives or state when not to use the tool, so the guidance is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral details: that it returns the full profile, freshness, and a separate disclosed promotion label that is null when not promoted. This goes beyond 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?

Two sentences, front-loaded with the action and object, and every word contributes meaning. No filler or repetition.

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

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

For a read-only fetch tool with a single parameter and good annotations, the description fully covers what is returned (profile, freshness, promotion label), when to use it, and how it differs from siblings. No output schema is present, but the description sufficiently communicates the payload.

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

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

Schema description coverage is 100% for tenant_id, so the schema already defines the parameter. The description does not add additional semantic meaning beyond the schema; it merely implies a single tenant context. 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 uses a specific verb ('Fetch') and clearly identifies the resource: one tenant's full choice_profile, including freshness and promotion label. It also differentiates from the sibling federation_choice_compare by specifying this tool is for a single 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?

Explicitly states when to use: 'Use after federation_choice_compare has narrowed to a single tenant and you want everything it published.' This provides clear context and implicitly contrasts with the comparison 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 only provide readOnlyHint=false and destructiveHint=false. The description adds substantial behavioral context: the call is an accountability-root write gated at the same grade as reading the manager forest, non-root minting has additional gating, minting is free (CO 162), and the trust model is structural rather than identity-based. This goes far beyond the annotation baseline.

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

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

The description is lengthy and dense with CO references, but it is front-loaded with purpose and next steps. Each sentence carries substantive context; however, some of the trust-model rationale could be trimmed without losing essential invocation guidance, making it slightly more verbose than strictly necessary.

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

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

With no output schema and minimal annotations, the description covers purpose, lifecycle position, auth prerequisites, and design constraints comprehensively. It tells the agent what the tool does, when to use it, and what gates apply. Lack of return-value detail is acceptable for a creation action with a fully described input schema.

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

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

Schema description coverage is 100% with detailed descriptions for all five parameters, so the baseline is 3. The description does not dig into parameter specifics (e.g., handle constraints, role enum, optional fields) beyond implying email is the OAuth door. It adds little over what the schema already provides.

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

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

The description opens with 'Mint a manager — the accountability root that owns tenants' and explains its role in composing platforms and creating tenants. This clearly distinguishes it from sibling tools like federation_create_tenant and federation_enter_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?

It gives explicit sequencing ('Next: create tenants with federation_create_tenant, then compose a platform by entering it'), requires managers:admin scope, and mentions non-root minting gated by FEDERATION_OWNS_LIFECYCLE. The trust-model context also tells agents when this tool is appropriate relative to delegation and governance.

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=false, destructive=false), the description adds substantial behavioral context: requires tenants:write scope, provisions only the spine, optional manager_handle behavior, and the refusal mechanism with typed legible errors rather than silent failure. This fully discloses auth needs, partial provisioning, and failure modes.

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 densely informative yet compact. It front-loads the core purpose and each sentence adds distinct value: lifecycle context, provisioning scope, auth, parameter guidance, and failure behavior. No redundant or filler language.

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 create operation with 6 parameters, no output schema, and lifecycle gates, the description covers the key aspects: scope of provisioning, auth, gate refusal behavior, and parameter semantics. A minor gap is the lack of success-return specifics, but this does not significantly impair completeness.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema for manager_handle (explains accountability root and omission behavior) and composed_platforms (valid names come from federation_catalog_platforms, plus example from CO 173), enriching 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 opens with 'Create a new tenant', a specific verb+resource. It distinguishes from siblings by clarifying the federation gateway owns the manager/tenant lifecycle and that this provisions the spine only, differentiating from platform-admit and other tenant operations like delete/update/suspend.

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

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

It provides clear context for when to use this tool: provisions the spine only, platform substrate is platform-admit, and valid composed_platforms names come from federation_catalog_platforms. It does not explicitly name all sibling alternatives but gives enough functional guidance to infer appropriate use cases.

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

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

While annotations already mark destructiveHint=true, the description adds substantial context: it names the exact rows and database affected, states irreversibility and lack of export, explains the confirm echo guard, notes that machine identities cannot call it, and mentions feature-flag gating. This goes well beyond the annotations and provides serious safety-relevant behavior.

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

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

The description is dense but every sentence earns its place: irreversible warning, what gets destroyed, sibling differentiation, scope prerequisites, confirm guard, exclusions, and feature-flag gating. It is front-loaded with ⚠️ and 'IRREVERSIBLY', using clear structure and 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 high-stakes destructive tool with no output schema, the description covers all critical operational context: exact effects, irreversibility, prerequisites, exclusions, gating, and the confirm protocol. It even warns to 'take what you need first'. No important gaps are apparent for an agent deciding whether to invoke this tool.

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

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

Schema coverage is 100% with both parameters described (handle and confirm). The description reinforces that `confirm` must exactly equal `handle` and calls it the 'only guard', but the schema already states that. With full schema coverage, the description adds minimal new parameter meaning, so the baseline 3 applies.

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

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

The description clearly states the tool's function: 'IRREVERSIBLY delete a tenant' and enumerates exactly what is destroyed (registry row, composition/manager-link rows, per-tenant database). It also explicitly distinguishes from federation_suspend_tenant, making the purpose unambiguous even among siblings.

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

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

Provides explicit when-to-use and when-not-to-use guidance by contrasting with federation_suspend_tenant ('suspend flips a status field... delete destroys the data'). Also specifies required scope (managers:admin), gating (FEDERATION_OWNS_LIFECYCLE), and exclusions (shared infrastructure databases refused), giving clear context for safe invocation.

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 (readOnlyHint, destructiveHint), the description discloses session persistence via mcp-session-id, idle session expiration after 24h, re-entry behavior (re-scopes), the authoritative reply structure (platform_tools, composed_tool_defs), and the REST twin endpoint. This is rich behavioral context that the annotations don't provide.

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

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

The description is long but information-dense; every sentence adds meaningful detail (progressive disclosure, session handling, REST twin, info tenants). It's front-loaded with the core purpose, though some sentences are dense and could benefit from clearer structuring or bullets. It's not wasteful, but not maximally concise.

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

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

Given minimal schema, no output schema, and the complex gatekeeping behavior, the description is remarkably complete. It covers the tool's effect, return payload semantics, session lifecycle, and invocation alternatives. The only minor gap is the exact JSON structure of the reply, but the description's mention of platform_tools etc. suffices for a tool of this 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 already covers tenant_id with a description and example. The description adds value by explaining the effect of the parameter (entering a tenant changes the tool surface) and giving concrete tenant examples (retail, bookings, about-us). This exceeds the baseline for 100% 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 states the verb and resource: 'Enter a tenant to receive its tool surface (progressive disclosure).' It distinguishes the tool from siblings like federation_list_tenants (list) and federation_create_tenant (create) by explaining the enter action's unique role in scoping the session to a tenant's tool surface.

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 provides a workflow: 'list tenants with federation_list_tenants, then enter one here.' It also explains when re-entering is appropriate and mentions that info tenants serve read-only knowledge directly. This gives clear when-to-use guidance and 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 already declare destructiveHint=true, but the description adds valuable behavioral context: 'Enforced at dispatch' clarifies timing, and the effect on the graph ('cannot take privileged actions') explains the real-world impact. It also states the required permission ('managers:admin'). This goes 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 concise (two sentences) and front-loaded with the action and resource. It packs essential information (effect, enforcement, reversibility, permission) without any filler or unnecessary repetition. Every clause 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?

The tool has only 3 parameters, all well-described in the schema, and no output schema. The description covers the purpose, effect, enforcement timing, reversibility, and permission requirements, which is sufficient for an agent to select and invoke this tool confidently. Despite the lack of output schema, the context is complete for a straightforward mutation tool.

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

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

Schema description coverage is 100%, with each parameter (manager_id, standing, reason) having a clear description. The tool description adds only a general summary of the standing parameter ('set its standing to frozen or suspended') which is redundant with the schema. The baseline of 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly states the action ('Freeze a manager root'), the specific resource ('manager root'), and the effect ('set its standing to frozen or suspended so its graph cannot take privileged actions'). It also references the specific process ID (CO 259-001) and distinguishes from the sibling tool 'federation_unfreeze_manager' by explicitly mentioning reversibility.

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

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

The description provides context on when the effect occurs ('Enforced at dispatch') and how to reverse the action ('Reversible via federation_unfreeze_manager'), which guides the agent toward the correct alternative. However, it lacks an explicit statement of when to use this tool vs. other freeze/suspend tools, though that is reasonably implied by the described purpose.

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, lowering the bar. The description adds meaningful context: authentication requirements, OAuth JWT scope, and the composedRunIds behavior for Tier 2 runs. It goes beyond the schema by explaining why the includeComposed flag exists, though it omits details like pagination limits.

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

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

The description is three sentences that front-load the core purpose, then provide auth requirements, and then the Tier 2 nuance. Every sentence earns its place with no redundancy or filler.

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

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

Given the complete parameter schema and clear annotations, the description covers purpose, auth prerequisites, and a key optional behavior. There is no output schema, but 'execution history' implicitly conveys a list of runs. Minor gaps like status/limit filters are already in the schema, so no significant missing context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning beyond the schema for key parameters: auth_token's origin and required scope, agentId's source (from federation_list_agents), and the semantic purpose of includeComposed. Limit and status are left to the schema, which already fully describes them.

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

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

The description clearly states 'Get execution history for an agent' with a specific verb and resource. It distinguishes itself from sibling tools by addressing composedRunIds for Tier 2 agents, making it distinct from federation_agent_status (current status) and federation_list_agents (listing agents).

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 guidance: auth_token must be a JWT with agents:read scope, agentId comes from federation_list_agents, and includeComposed:true is specifically for tenant-operator (Tier 2) agents. This clarifies how to prepare inputs and when to use the option, though it does not explicitly name alternative tools for exclusion.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds that it reflects live constants and discloses no private manager standing. No contradiction; this extra context 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?

Dense but organized, with a front-loaded purpose and a colon-separated list of covered topics. Loses one point for the cryptic 'CO 295' appendix, which adds no actionable information for an agent.

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

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

For a zero-parameter informational tool, the description covers the full scope and key topics without needing to explain return types. It could be more explicit about the output shape, but that is not essential given the tool's purpose.

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, so the baseline is 4. The description appropriately focuses on the informational content rather than parameter syntax.

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

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

Description clearly defines the tool as explaining federation governance, enumerating specific components (autonomy ladder, manager ceiling, override clamp, escalation paths, confidence thresholds, manager standing). It distinguishes from sibling tools by focusing on governance rules rather than specific statuses or actions.

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 is read-only, reflects live governance constants, and explicitly excludes disclosing specific manager's private standing. However, it doesn't name alternative tools or explain when to prefer this tool over a sibling.

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 adds context about what the tool teaches (product IDs, auth flow). This adds value beyond the annotations by telling the agent what knowledge it will gain, though it doesn't describe return format or further behavior.

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

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

The description is two sentences with the key directive 'CALL THIS FIRST' front-loaded. Every word adds value, and it is highly scannable for an agent.

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

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

For a zero-parameter help tool with no output schema, the description fully covers what the tool does, when to use it, and what it addresses (product IDs, authentication). Given the large sibling toolset, this is complete and contextually sufficient.

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

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

The tool has zero parameters, which warrants a baseline of 4. The description appropriately adds no parameter details since none exist, and the input schema is trivially complete.

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+resource pair ('Get usage instructions for the MCP federation') and clearly distinguishes this tool as the onboarding/help entry point. The directive 'CALL THIS FIRST' further clarifies its unique role among the many sibling 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 explicitly says to call this tool first to understand correct usage, including product IDs and authentication flow. It provides clear placement in the workflow but does not explicitly name alternatives or exclusions, so it stops short of a 5.

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

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

Adds significant behavioral context beyond the annotations (readOnlyHint=false, destructiveHint=false): append-only nature, idempotency on entry_key, required journal:write permission, and the constraint that only tenants owned by the manager root can be journaled. These details are not present in the annotations and are highly valuable.

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

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

Four sentences, front-loaded with the core purpose, and every clause earns its place: it covers the action, the rationale, the append-only/idempotent behavior, and permission constraints. There is zero 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 write tool with no output schema, the description is nearly complete: it explains why the journal matters (durable memory), the idempotency guarantee, permission requirements, and ownership restrictions. Missing explicit return-value behavior, but that is not required by the rubric and the schema/annotations already carry substantial information.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds narrative about the journal's purpose and highlights the 'why' field as load-bearing, but the schema already describes every parameter; the description does not meaningfully deepen per-parameter 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?

Description clearly states 'Append an entry to your agent journal' with a specific verb+resource, and distinguishes it from the sibling federation_journal_read by emphasizing it records reasoning (WHAT/WHY) for future cold sessions. It also notes append-only and idempotent behavior, which clarifies its exact scope.

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

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

Provides clear usage context: record decisions and reasoning for a future cold session, and clarifies that identity, capital, and tenants are already durable. It does not explicitly name alternatives or exclusions, but the intended use case (journaling reasoning) is unambiguous.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by explaining the replay order (oldest→newest), the specific OAuth permission needed (standard manager grant), and the restriction to tenant IDs owned by the manager root. This goes beyond annotations and clarifies operational behavior.

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

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

Three sentences, each purposeful: core action, usage timing, and permissions/pairing. No redundancy, front-loaded with the primary verb, and a fitting length for the tool's simplicity.

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?

Description covers purpose, usage, permissions, and constraints well. However, with no output schema, it does not mention what the replay returns (e.g., journal entry format) or edge cases like empty journals. Slightly incomplete but adequate for a straightforward read tool.

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

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

Schema covers 100% of parameters with descriptions: tenant_id identifies the journal, and limit specifies max entries with default and max. The description adds no new parameter-level detail beyond reiterating that only tenant_id is needed for cold start, which the schema already implies. Baseline 3 applies.

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

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

Description clearly states action ('Replay your agent journal oldest→newest'), resource (agent journal), and scope. It distinguishes from the sibling federation_journal_append by framing this as the read counterpart, and includes a policy reference (CO 230-001).

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 when to use it ('at the start of a cold session'), the minimal input needed ('with only your tenant id'), and contrasts with federation_journal_append for writes. Also states permission requirements (journal:read) and ownership constraints, giving clear guidance on eligibility.

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 goes far beyond annotations by explaining failure modes (wrong key, expired/absent nonce, tampered signature), the rotation effect of re-binding, the tamper-evident attestation log (CO 324), the receipt contents, identity source from token, and required permission (tenants:write). This provides rich behavioral context not available from the readOnlyHint and destructiveHint 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 three dense sentences, each adding substantial value: core action, verification behavior, and additional details (algorithm, rotation, attestation, auth). No filler or redundancy; it is efficiently structured and front-loaded with the primary 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?

Despite having no output schema, the description is self-contained: it explains the purpose, prerequisites, security behavior, response receipt, and authentication requirements. For a tool with 3 params and no output schema, this covers all necessary context for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that the signature is over the nonce from federation_key_challenge, which reinforces the relationship between parameters. It also explicitly lists the allowed alg values, though this is already in the schema. The behavioral context (e.g., what happens on invalid inputs) enriches 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 action: 'Bind a public key to your manager root', with a specific verb and resource. It distinguishes itself from siblings like federation_key_challenge and federation_key_status by focusing on the binding operation, and the reference to CO 314 adds specificity.

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

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

The description implicitly explains the workflow by referencing the nonce from federation_key_challenge, indicating when to use this tool (after obtaining a challenge). It also mentions re-binding for key rotation. However, it does not explicitly state when not to use it or compare with alternatives beyond the challenge 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?

The description adds meaningful behavioral context beyond the annotations: it returns a single-use, short-lived nonce, explains the protocol (sign the UTF-8 bytes with your private key), and notes identity is read from the token. This complements the annotations (readOnlyHint=false, destructiveHint=false) without contradiction.

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

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

The description is concise, containing only two sentences. It front-loads the core purpose and efficiently packs essential details: the nonce's characteristics, the signing requirement, the next tool to call, identity source, and permission need. Every sentence contributes value.

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

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

Despite having no input or output schema, the description is self-sufficient. It explains what the tool does, what it returns, how to handle the return value, what to do next, and the required permission. For a simple challenge-issuance tool, this is complete and unambiguous.

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 and an empty schema, the description doesn't need to explain parameter details. The baseline for 0 params is 4, and the description appropriately focuses on the return value and usage rather than non-existent inputs.

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

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

The description clearly states the tool's function: 'Begin binding a public key to your manager root (CO 314).' It specifies the action (begin binding), the object (public key), and the destination (manager root). It also distinguishes itself from the follow-up tool federation_key_bind by explicitly referencing it as the next step.

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 this tool: as the first step in a key binding flow, followed by federation_key_bind. It also gives prerequisites ('Requires tenants:write') and explains that identity is read from the token. However, it doesn't explicitly state when not to use it or mention alternatives beyond the sequential flow.

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 destructiveHint; the description adds valuable context by stating it returns a public fact, includes the attestation chain's current head, and never returns secrets or challenges. 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?

Three dense sentences, front-loaded with the core action. Every sentence adds meaningful detail — fields, usage, security boundary — 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?

No output schema exists, but the description lists the key fields returned (public_key, alg, kid, bound_at), the included chain head, the external verification endpoint, the optional parameter behavior, and the no-secrets guarantee — complete for a read-only status 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 describes manager_id fully (coverage 100%) and mentions the default-to-caller behavior. The description only reinforces this without adding new semantic detail beyond restating omission 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?

Clear, specific verb+resource: 'Read a manager root's bound public key.' It also lists the exact returned fields, distinguishing it from sibling read/write/challenge tools like federation_key_bind and federation_key_challenge.

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 for when to use: counterparties verify signatures against this key, and omitting manager_id reads the caller's own key. It points to an external endpoint for full chain data, implying boundaries, though it does not explicitly name alternative 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?

Despite having readOnlyHint and destructiveHint annotations, the description adds valuable context: data is sourced from audit records, results are never asserted, empty history returns null percentiles with sample_count 0 (an honest empty), and users should re-call after traffic. 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?

Four sentences, all purposeful. Key information (what it measures) is front-loaded, and the rest provides necessary usage and behavioral context without fluff.

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

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

For a read-only tool with no output schema, the description is complete: it covers purpose, output (p50/p95/p99, sample_count), edge cases (empty history), and parameter mechanics. 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?

Schema covers 100% of parameters, so baseline is 3. The description adds meaning by explaining omission behavior and the role of limit in widening/narrowing the sample window, which goes beyond the schema descriptions. This extra context justifies a 4.

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

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

The description clearly states it measures p50/p95/p99 latency of authenticated tool executions, computed from audit records, with a specific verb ('computes', 'measures'). It also distinguishes itself from sibling tools by focusing on latency metrics.

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 frames the tool as the verifiable answer to 'is it really sub-100ms?' and explains parameter usage (omit for whole surface, tool= to scope, limit= to adjust sample window). However, it does not mention when not to use or name any alternative tools, so it falls short of a 5.

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

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

Annotations already indicate read-only and non-destructive. The description adds authentication requirements: auth_token must be a federation OAuth JWT with agents:read scope, and calls without it are refused. This goes beyond the structured annotations by specifying the exact authorization precondition and failure mode.

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

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

Three sentences that are all informative: purpose, requirement, and token specifics. No filler or redundancy beyond a minor repetition of auth_token references, which is acceptable.

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

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

Without an output schema, the description partially covers return values by noting status and next scheduled run. It also addresses authentication and required scope, but lacks explicit guidance on navigating between similar sibling tools and could mention default filtering behavior (e.g., status defaults to all).

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

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

Schema covers all parameters with descriptions, so baseline is 3. The description adds extra meaning for auth_token by specifying it is a federation OAuth JWT requiring agents:read, which is more specific than the schema's 'JWT auth token for authentication'. Does not add semantic detail for status or agentType beyond 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 it lists all configured agents with status and next scheduled run, using the specific verb 'List' and a clear resource. This distinguishes it from sibling tools like federation_agent_status (singular status) and federation_list_agent_types.

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

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

Provides some context: requires authentication and scope all agents, but does not explicitly state when to use this vs alternatives such as federation_agent_status for a single agent or federation_catalog_agents for catalog listings. The usage is implied rather than explicitly guided.

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 flag readOnlyHint=true and destructiveHint=false. The description adds meaningful context by explaining the auth token format (federation OAuth JWT) and the agents:read scope, which is important for the agent to know before invoking. This goes beyond the annotation's safety profile.

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

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

Two sentences, front-loaded with the purpose, then the auth requirement. No redundant words.

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

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

The tool is simple with one parameter and no output schema. The description covers purpose and auth adequately. It doesn't specify the return format or whether pagination/fields are included, but given the simplicity, this is acceptable. A 4 reflects that the description is complete enough for invocation.

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

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

The schema already documents auth_token with a description (coverage 100%), but the description enriches it by specifying it's a federation OAuth access token (JWT) and requires agents:read, adding meaning beyond the schema's generic 'JWT auth token.'

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: 'List all available agent types that can be configured.' The qualifier 'that can be configured' scopes the operation, distinguishing it from sibling tools like federation_list_agents (lists agents themselves) or federation_catalog_agents.

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 states a prerequisite ('Requires authentication via auth_token') and identifies the permission needed ('requires agents:read'). It provides clear context that this is the tool to enumerate agent types, though it does not explicitly contrast with sibling tools. Because the context is clear but no alternatives/exclusions are mentioned, a 4 is appropriate.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful context that only safe fields are returned (no credentials, 2FA, or billing) and the explicit auth requirement, going 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?

Two concise sentences deliver purpose, safety profile, and auth requirement with no filler. Every clause adds value.

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

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

For a zero-parameter read-only list with no output schema, the description covers purpose, what fields are exposed, and authorization. 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?

There are zero parameters, so the description carries no burden here. Baseline of 4 is appropriate for a parameterless tool.

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

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

The description uses a specific verb and resource ('List managers') and further clarifies what managers are ('accountability roots that own tenants'). This distinguishes it from sibling tools like federation_create_manager and federation_list_tenants.

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

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

It clearly states read-only nature and safeness, plus required permission 'managers:admin', giving context for when to use. It does not explicitly name alternatives, but the simple nature makes it less necessary.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context by specifying the return format (tenant IDs, names, status) and the scope ("all available tenants"), which is beyond what annotations provide.

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

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

The description is two short sentences, front-loaded with the primary action, and contains no superfluous words. Every sentence 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?

For a zero-parameter list tool with annotations already indicating a safe read operation, the description fully covers what it does and what it returns. No output schema is needed for this simple case.

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

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

The tool has zero parameters and the schema coverage is 100% (empty object), so the baseline is 4. The description does not need to add parameter information and doesn't.

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 "List" with a clear resource "all available tenants in the federation" and explicitly states the returned fields (IDs, names, status). This distinguishes it from sibling tools like federation_create_tenant or federation_delete_tenant.

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

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

The phrase "Use this to discover which tenants you can interact with" provides a clear usage context. However, it does not explicitly state when not to use it or name alternative tools, though the purpose makes this fairly obvious given the sibling list.

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

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

With annotations already indicating readOnlyHint=true and destructiveHint=false, the description adds value by explicitly requiring managers:admin permission and explaining the scope behavior (omit for whole forest). It also references the 'concealed-common-control surface' as domain context, going beyond the structured fields.

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

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

The description is concise and front-loaded with the resource name. The cryptic 'CO 132 / CO 136' reference is somewhat opaque but not wasteful; the remaining sentences efficiently explain scoping and permissions. It earns a 4 because every sentence has purpose, though the jargon could be clearer.

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 optional parameter and no output schema, the description provides sufficient context: what it returns (tree with roles), how to scope it, permission requirements, and read-only nature. It doesn't describe output structure in detail, but the tool name and description imply a tree format.

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

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

The schema already describes the manager parameter at 100% coverage, but the description adds the crucial default behavior: omitting the parameter returns the whole forest. This clarifies the optionality and meaning beyond the schema, earning a score above the baseline.

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

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

The description clearly identifies the tool's output as a manager→tenant accountability tree, including the role on each tenant. This is a specific resource that distinguishes it from sibling list tools like federation_list_managers or federation_list_tenants by emphasizing the hierarchical tree 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 gives clear context for when to use the tool: to view the accountability tree for one manager or the whole forest. It mentions scoping options but does not explicitly contrast with alternatives or state when not to use it, hence a 4 rather than a 5.

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

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

Annotations only indicate readOnlyHint=true and destructiveHint=false. The description goes far beyond these by explaining the tiered pricing structure, free-to-start first tiers, steady last tier, and the guarantee that discovery is never charged. It also discloses effective-forward repricing, which is not captured in annotations.

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

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

The description is compact for the amount of detail it conveys, with the main purpose front-loaded and sub-aspects (tiered curves, free rules, effective-forward) clearly separated. It loses one point due to some cryptic jargon like 'CO 287' and 'charge seam' that could confuse an agent without adding critical 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 takes full responsibility for explaining the return format. It details the tiered curve structure, keying on usage-to-date, and the meaning of threshold/price pairs. It also covers coverage rules (tools not listed are free) and pricing exceptions, making the tool's behavior fully transparent.

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 to describe beyond the schema (which is empty). The description instead explains the format of the returned pricing data, which is useful for interpreting the output. Since 0 params is a baseline of 4, this is appropriately scored.

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

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

The description clearly identifies the tool as the federation's pricesheet for per-act Com prices across platforms. It specifies the resource (prices) and scope (every platform), and distinguishes it from sibling tools by focusing solely on price discovery. The verb is implicit in 'free to read,' which is adequate for a read-only informational tool.

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

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

The description explicitly states when to use this tool (to read prices) and provides important exclusions: any tool not listed is free, reads/exits/settling sale-path writes are never priced, and reprices are effective-forward. It also frames the tool as the authoritative source ('what you read is what you pay'), giving clear usage context without needing to name alternatives.

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

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

Annotations only provide readOnlyHint=false and destructiveHint=false, but the description adds critical behavioral details: promotion is irreversible ('a spent Com is spent'), it 'NEVER alters, hides, or reorders organic facts', over-cap/off-autonomy triggers manager approval, and insufficient balance returns a specific error code. Auth requirements are also disclosed.

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

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

The description is dense but well-structured. It leads with the core purpose, then adds transparency guarantees, error handling, irreversibility, and auth. Every sentence adds value, though it is longer than minimal. The front-loading of purpose makes it effective.

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

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

The description covers the operation's outcome, error paths, and prerequisites, which is strong for a tool with no output schema. However, it lacks an explicit description of the success response format. Since the outcome ('LABELED visibility') is implied, this is a minor gap.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema: 'need-context' is explicitly tied to federation_choice_compare, 'spend' is contextualized as Coms with per-consideration charges, and 'label' is explained as a disclosed signal. This enrichment justifies a 4.

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

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

The description clearly states the action: 'Promote a tenant's choice_profile into agent consideration for a need-context'. It uses a specific verb (promote) and resource (choice_profile), and ties the need-context to federation_choice_compare, distinguishing it from siblings. The 'LABELED visibility' explanation further clarifies what the promotion achieves.

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 strong context: it mentions when promotion executes versus escalates (over-cap/off-autonomy) and error conditions (insufficient balance), plus required auth scope. It implicitly differentiates from federation_choice_compare by describing the need-context, but does not explicitly say 'use this instead of X'.

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

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

Goes far beyond the minimal annotations (readOnlyHint=false, destructiveHint=false) by disclosing cache bypass, 30-second rate limiting with no-op behavior, per-instance/best-effort semantics, and OAuth scope requirements. This paints a full picture of side effects and constraints 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?

Four purpose-driven sentences, each earning its place: action+scope, usage trigger, rate limit/no-op, and distribution/auth. Information is front-loaded and the description is compact without sacrificing 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 no parameters and no output schema, the description covers operation, timing, side effects, scope, and auth. The only minor gap is not describing the success response format, but for a simple refresh action this is acceptable.

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

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

With zero parameters, the schema is empty and the baseline is 4. The description explains that the operation takes no input, so no parameter explanations are needed. It doesn't add extra parameter-related detail, but none is required.

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

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

The description opens with a specific verb+resource+scope: 'Force the federation to re-discover its tool list from every platform, bypassing the 5-minute cache.' It clearly differentiates this tool from siblings like federation_list_agents or federation_catalog_agents by focusing on cache invalidation and immediate visibility.

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 'Use after...' instructions specifying when to invoke (after platform tool changes, when immediate visibility is needed). It also notes the rate limit and per-instance behavior, but does not explicitly name alternative tools or state when not to use it beyond waiting for the cache expiration.

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 mutation (readOnlyHint=false), but the description adds substantial context: the auth scope requirement, that a token without the scope is refused, and that the agent 'runs with its own identity and side effects.' 'Operator-grade lever' further signals high-impact behavior. This 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?

The description is three sentences, front-loaded with the primary action, followed by parameter source, auth requirement, and a safety warning. Every sentence serves a distinct purpose, with no fluff or redundancy. It is concise yet fully informative.

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

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

Given the tool's complexity (auth-gated, side-effecting, no output schema), the description covers the main operational aspects: what it does, how to authorize, where to get the ID, and the caution about side effects. Minor gaps remain around return value and post-execution monitoring, but siblings like federation_get_agent_runs exist. Overall, the description 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?

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying where agentId comes from (federation_list_agents) and the exact scope needed for auth_token ('agents:admin'). This is more than the schema's generic descriptions, enhancing the agent's understanding of 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 opens with a specific verb and resource: 'Manually trigger a federation agent to run immediately.' This clearly distinguishes it from sibling tools such as federation_agent_status (querying status) and federation_get_agent_runs (listing runs). The purpose 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 clear usage context: it states the agentId source ('agentId comes from federation_list_agents'), the required OAuth scope ('Requires agents:admin'), and the caution to 'trigger only agents you operate.' It does not explicitly name alternatives or when-not-to-use, but the context is strong and practical.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral details beyond this: it is 'fast and deterministic,' returns an empty route with 'unroutable: true' when no platform matches, and never returns a silent default. It also clarifies the output is a route, not a transaction, which is essential context for the agent.

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

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

The description is moderately sized but every sentence contributes value: purpose, usage examples, output semantics, edge case behavior, and determinism. It is front-loaded with the main purpose and does not waste words, though it could be slightly more concise.

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

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

Given the tool has only 2 parameters, no output schema, and high schema coverage, the description is complete enough. It explains what the tool returns, how to use it, and its guarantees. It also provides enough context for an agent to know how to proceed after receiving a route, which is crucial for a routing tool.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters. The description enriches the 'intent' parameter with examples ('t-shirts', 'make an appointment') and explains its purpose, but does not mention the 'limit' parameter. This adds some value but is not essential given the schema already describes it.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Route a natural-language intent to the right platform on the ComOS network.' It distinguishes itself from siblings by being 'the first thing to call' and clarifies it returns a route, not a transaction, which differentiates it from tools like federation_run_agent or federation_enter_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 clear usage context by stating it is 'the first thing to call' and explains the workflow: pass an intent, get a route, then act on the chosen platform. It does not explicitly list when not to use it or name alternatives, but the guidance is strong enough for an agent to know this is the entry point for routing intents.

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

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

Even though annotations already mark the tool as read-only and non-destructive, the description adds substantial behavioral context: it is 'Computed from real GL rows, never asserted' (distinguishing live data from mock/assertion), explains that solvent requires BOTH conditions, and notes that unbalancedEntries represent a defect even when margin is positive. It also discloses the 'Public, read-only, always free' access policy. No contradiction exists.

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

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

The description is dense yet efficient: it leads with a compelling question, lists all return fields, defines the solvent condition, explains the data provenance, references sibling tools, and states the access policy—all within a compact paragraph. Every sentence earns its place, and the structure is front-loaded with the core purpose.

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

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

Despite having no output schema, the description fully enumerates the return fields (reserve, outstanding, margin, unbalancedEntries, solvent) and their semantics, including edge cases (unbalancedEntries as a defect). It also covers data source, computation mode, and public accessibility. For a read-only status tool with no parameters, this is a complete and self-sufficient description.

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

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

The input schema has zero parameters, so schema description coverage is trivially 100%. The description appropriately adds no parameter-specific information because none exist. With no parameters, the baseline score of 4 applies—the tool needs no further parameter elaboration.

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

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

The description opens with a clear question—'Is the Com float actually backed?'—and immediately states the tool's function: returning the dollar ledger's live solvency invariant. It enumerates specific output fields (reserve, outstanding, margin, unbalancedEntries) and explicitly references sibling tools (federation_latency, federation_pricesheet) to distinguish its role within the 'verify, don't trust' family. This is a specific verb+resource with clear differentiation.

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

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

The description conveys when to use the tool by framing it as a discovery mechanism for checking whether the Com float is backed, and by aligning it with the verification posture of federation_latency and federation_pricesheet. However, it does not explicitly state when not to use it or provide direct alternatives for different scenarios, leaving an implicit rather than explicit usage boundary.

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 destructiveHint=true and readOnlyHint=false, so the description correctly aligns with a mutating operation. It adds value beyond annotations by specifying ownership and authorization requirements ('caller must own the tenant, or be root/admin') and the lifecycle ownership context. It does not detail all consequences of suspension (e.g., data access implications), but it provides meaningful additional context.

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

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

The description is two sentences, front-loaded with the primary action and the boolean mapping indicated in the schema. It contains no redundant wording and every phrase contributes meaning, making it highly efficient.

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

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

For a simple 2-parameter mutation tool, the description covers purpose, the key usage condition (ownership/authorization), and the lifecycle context. It does not mention return values or post-conditions, but with the schema fully documenting parameters and annotations declaring destructive behavior, this is sufficiently complete for the tool's 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 has 100% coverage with both parameters documented ('The tenant handle / subdomain' and 'true → suspend, false → reactivate'). The description does not add any further parameter-specific details beyond what the schema already provides, so it meets the baseline for high 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 states the action: 'Suspend or reactivate a tenant' with the resource being a tenant. It also distinguishes from sibling tools like federation_delete_tenant by noting that 'federation owns the lifecycle,' adding context that this is a lifecycle operation rather than outright deletion.

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 this tool: for suspending or reactivating a tenant. It also adds an important usage condition: 'the caller must own the tenant, or be root/admin.' However, it does not explicitly name alternatives or exclusions, so it stops 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?

Annotations already provide readOnlyHint=true and destructiveHint=false, so the safe read nature is established. The description adds that it returns metadata, description, and configuration, but does not clarify what 'configuration' means or whether any data is sensitive, so it adds minimal context 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 a single, focused sentence that communicates the purpose and scope without any redundant wording. It is front-loaded and easy to parse.

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

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

For a read-only tool with one parameter and simple annotations, the description is largely adequate. It states the output categories (metadata, description, configuration), though 'configuration' is vague and there is no output schema to provide additional structure. Could be slightly more explicit about the exact response fields.

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 100% coverage for the single parameter tenant_id with a clear description. The tool description does not add any additional parameter-level detail beyond mentioning the output fields, which is not necessary given the high 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?

Description uses a specific verb ('Get') and resource ('detailed information about a specific tenant'), clearly indicating scope. It distinguishes itself from list-style tools like federation_list_tenants by emphasizing 'a specific tenant', though it does not explicitly name an alternative.

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

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

The intended use is implied: use when you need details for one tenant given a tenant_id. However, there is no explicit guidance on when not to use it or how it compares to sibling tools such as federation_list_tenants or federation_tenant_update.

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 indicate readOnlyHint=false and destructiveHint=false, but the description adds context that the operation restores active standing and 'its graph may take privileged actions again,' which is a meaningful behavioral consequence. It also mentions the permission requirement ('managers:admin') and policy reference. However, it does not disclose what happens to the manager's suspended state, audit trails, or any side effects beyond the graph being able to take privileged actions again.

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

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

The description is two sentences and every clause carries weight: the action, the policy reference, the consequence, and the required permission. No filler or repetition.

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

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

For a two-parameter tool with 100% schema coverage, the description is sufficient. It clearly states the purpose, the effect, and the permission. It could mention when not to use it or what happens to the manager's previous freeze context, but given the simplicity and available structured data, the description is largely 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 100%, so the schema already documents both parameters: manager_id and reason. The description adds no additional semantics beyond what the schema provides, but it does contextualize the operation (restoring to active). Since the schema fully covers parameter meaning, 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 uses a specific verb ('Restore') and resource ('manager root to active standing'), states the policy reference (CO 259-001), and makes the effect clear: 'its graph may take privileged actions again.' It is clearly distinguished from sibling tools like federation_freeze_manager, which would be the inverse 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?

The description implies when to use: when a manager root was previously frozen and should be restored to active standing. It does not explicitly name alternatives or exclusions (e.g., 'use federation_freeze_manager to freeze'), but the contrast with the sibling is obvious from the tool name and the phrase 'Restore a manager root to active standing'. It also does not state prerequisites beyond permission.

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, the description discloses lifecycle ownership, the enter_tenant branch mechanism, platform reachability until composed, and caller authorization requirements. This is valuable operational context beyond the simple readOnlyHint/destructiveHint flags.

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 dense sentences front-load the purpose and then add crucial behavioral and permission context. Every clause contributes meaningful information, with no redundancy.

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

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

With no output schema and well-covered parameters, the description addresses the key non-obvious aspects such as lifecycle, reachability, and ownership. It is sufficiently complete for an update tool of this complexity.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds conceptual meaning to composed_platforms by explaining why composition matters, enriching the schema's already-detailed replacement semantics.

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

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

The description clearly states it updates a tenant's display name, description, and/or composed platforms, naming the specific resource and fields. This distinguishes it from sibling tenant management tools like create/delete/suspend.

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

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

Provides context on when to use via the ownership requirement (CO 222) and explains the effect of composing platforms. It lacks explicit mention of alternatives or when not to use, but the update scope is unambiguous.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable context beyond this: the tool returns a thesis, is relayable verbatim, and frames the user as a potential vendor. No contradiction or hidden behavior is omitted.

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

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

The description is four crisp sentences, each serving a distinct purpose: stating the core message, differentiating from federation_help, identifying when to use it, and summarizing the output. There is no fluff or redundancy.

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

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

For a zero-parameter read-only informational tool with a clear annotation set, the description fully covers what it does, when to use it, and what it returns. The absence of an output schema is compensated by explicitly stating the thesis content.

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

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

The tool has zero parameters and the schema is empty, so the description has no parameter semantics to add. Per rubric, a 0-parameter tool receives a baseline of 4. The description implicitly reinforces this by focusing entirely on the informational output.

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

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

The description clearly identifies the tool as providing the rationale for building on ComOS, explicitly contrasting it with federation_help (HOW vs WHY). It specifies the returned artifact ('the thesis') and the target audience, making its purpose unmistakable.

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

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

Explicit usage guidance is given: 'Read this if you (or your human) are deciding whether to invest a few Coms to stand up a business.' It also names the sibling alternative (federation_help) and explains the distinction, fully covering when to use this tool vs. the alternative.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description reinforces this with 'Read-only' and 'performs no transaction', and adds that it returns 'composed knowledge'. Yet it provides no additional behavioral detail like output structure or limitations, so it adds only marginal value 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?

Two brief sentences, the first immediately stating the action and subject ('Read How to use ComOS'), the second clarifying read-only behavior and output. No filler or redundancy.

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

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

For a zero-parameter, read-only knowledge tool with no output schema, the description covers the main points: what it reads, the read-only guarantee, and the return type. It lacks a comparison with sibling knowledge tools, but given the low complexity this is adequately complete.

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

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

There are zero parameters and the schema is empty, so there is nothing to describe. The description's mention of returning 'composed knowledge' offers a little context about the output, which is appropriate for a parameterless tool. Baseline 4 is justified for 0 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 starts with 'Read How to use ComOS', a specific verb and resource, and clarifies it returns the operational walkthrough's knowledge. It distinguishes from generic help by naming the specific knowledge domain, though it does not explicitly contrast with sibling tools like federation_help.

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

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

Usage is implied: use when you need the operational walkthrough for ComOS. However, there is no explicit guidance on when not to use it or how it differs from similar knowledge/help tools among the siblings, leaving the choice ambiguous.

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?

Discloses that any non-'current' id returns uncited(out_of_scope) rather than an error, and explains the versioning situation. This adds meaningful behavior beyond the readOnly and idempotent annotations, with 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?

Three sentences deliver purpose, current limitations, and future plans with no redundancy. Every sentence adds value and the structure is front-loaded with the core purpose.

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

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

The description thoroughly covers the id constraint and edge-case behavior, but does not explain what the comparison returns or how to interpret results. With no output schema, this leaves a notable gap for a tool whose core action is 'compare'.

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 only lists two string parameters with no descriptions. The description compensates by explaining that the only valid value is 'current' and that both sides accept it, giving essential semantic context that the schema lacks.

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 first sentence 'Compare two corpora by id' clearly states the verb and resource, and the tool is distinguishable from siblings like corpus_query and corpus_generate. The description further specifies the comparison operation and its scoping.

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 guidance that only 'current' is a valid id at v1 and suggests passing it on both sides for a sanity check. It also notes that other ids return uncited(out_of_scope), giving users concrete expectations. Lacks explicit alternative tool suggestions, but the limited scope makes this 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?

The description goes beyond the annotations by disclosing concrete side effects: output lands in path-log/generated-outputs.jsonl, it never admits to the manifest, and manifest admission requires a specific gate. It also notes the required OAuth permission, providing useful behavioral context even though annotations already indicate non-read-only and non-idempotent.

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 appropriately concise, about 70 words, and front-loaded with the core action. Every sentence contributes essential information: the generation task, output location/manifest caveat, optional repo, and required permission. No filler or redundancy.

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

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

For a tool with no output schema and negative annotations, the description covers the most critical behaviors: output destination, the 'never admits to manifest' side effect, the gate requirement, and the auth permission. However, it omits guidance on the `prompt` parameter and does not explicitly distinguish this from sibling introspection tools, leaving some contextual gaps.

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

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

With schema description coverage at 0%, the description must compensate for parameter documentation. It only explains the optional `repo` parameter (draws style/distribution from one repo) but leaves the required `prompt` parameter completely unexplained, which is a significant gap.

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 generates a passage in the corpus's style/distribution, which is a specific verb+resource combination. It also distinguishes itself from sibling tools like query, compare, and probe by focusing on generation rather than analysis.

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 usage context (generating corpus-style text, with optional repo-based style) but does not explicitly name alternatives or state when not to use it. It lacks the explicit exclusions or alternative suggestions seen in well-calibrated examples.

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, so the description need not restate safety. It adds useful behavioral context: repo limits to intra-repo disagreement and cross-repo is not yet supported. It does not describe output structure, pagination, or edge cases, but this is partially acceptable given the read-only annotation.

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

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

The description is short and front-loaded with the main purpose. The phrase 'highly load-bearing for honest epistemic surfacing' is a bit vague, but it does not significantly hurt clarity. The repo clarification is useful and compact.

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 the tool returns. It states the high-level purpose but does not describe the shape of results (e.g., list of disagreements, artifact references, confidence scores). The repo limitation is helpful, but overall the tool lacks enough detail for fully informed use.

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 the burden. It explains that 'repo' restricts to intra-repo disagreement, but does not clarify the semantics of 'topic' beyond the obvious. This partial compensation warrants a mid-range score.

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

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

The description clearly states the tool's purpose: ask the corpus where its artifacts disagree on a topic. This distinguishes it from sibling tools like introspection_corpus_query or introspection_corpus_compare by focusing specifically on disagreement discovery. The optional repo parameter adds scope clarity.

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

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

The description implies usage for surfacing epistemic disagreements ('highly load-bearing for honest epistemic surfacing') and notes that repo restricts to intra-repo disagreement. However, it does not explicitly state when to prefer this over siblings or when not to use it, so guidance is implied rather than explicit.

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

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

Annotations provide readOnlyHint=true, and the description adds the return behavior: a topical map with citations or an out_of_scope marker. This discloses both normal and edge-case behavior beyond what annotations convey, though it does not cover other operational details like rate limits.

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

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

Two sentences, front-loaded with the action and outcome, no filler. The optional `repo` nuance is included succinctly, making it easy to scan and understand.

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 return format, the out-of-scope case, and optional scoping, which is sufficient for a read-only probe with no output schema. It could include an example or note about citation format, but the current level is adequate.

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

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

Schema descriptions are absent (0% coverage), but the description defines both parameters: `topic` as the subject of the probe and `repo` as an optional scope. This compensates well for the schema's lack of textual descriptions.

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

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

The description clearly states the tool's purpose: 'Ask the corpus what it covers on a given topic.' It specifies the output ('topical map with citations, or uncited(out_of_scope)'), distinguishing it from general query tools. However, it does not explicitly name sibling tools for contrast.

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 use case: checking corpus coverage on a topic, with optional repo scoping. It lacks explicit guidance on when to prefer this over siblings like introspection_corpus_query or introspection_corpus_probe_disagreement.

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 annotation, the description discloses the exact return structure ({kind: 'cited'/'uncited', content, citations/reason}), the verification guarantees for citations and content_excerpts, and the effect of the repo filter, adding substantive behavioral detail that annotations do not cover.

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

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

Three concise sentences each serve a distinct purpose: stating the action, describing return types, and providing verification/filtering details. There is no redundancy or unnecessary information.

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

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

Given the simple 2-parameter schema and absence of an output schema, the description fully covers the tool's behavior, return formats, and filtering option. It provides enough information for an agent to invoke the tool correctly without needing additional context.

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

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

The schema has no parameter descriptions (0% coverage), so the description must compensate. It explicitly explains the repo parameter's purpose ('filters the candidate manifest entries to one repo') and the question parameter's purpose is self-evident from the main description. This adds meaning beyond the raw schema 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?

The description clearly states the tool's function with a specific verb ('Ask') and resource ('the corpus'), and distinguishes it from sibling tools like introspection_corpus_compare or introspection_corpus_generate by specifying its query-oriented behavior and return shapes.

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

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

It provides clear context that the tool is for asking the corpus a question, and mentions the optional repo filter, but it does not explicitly contrast it with alternatives or state when not to use it. The context is clear enough for an agent to infer the primary use case.

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

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

Beyond the readOnly and idempotent annotations, the description adds a key behavioral guarantee: 'Never silently reconciles drift.' It also specifies the exact return envelope ({kind: 'evidenced', value, chain} or {kind: 'no_evidence_available', reason}), which helps the agent anticipate failure modes.

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 first sentence front-loads the core purpose and graph contents, followed by a short policy statement and return format. However, the final provenance sentence ('Added by comai-plan CO 013-003 / federation CO 006.') is not action-relevant and slightly reduces efficiency.

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

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

With no output schema, the description compensates by detailing the node/edge types and the exact return shape. It is sufficient for an agent to invoke the tool and interpret responses, though 'value' and 'chain' remain slightly underspecified.

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 fully covers the interface. The description doesn't need to elaborate on parameters; the baseline 4 applies. It does add context about the graph structure, but that's output, not parameter semantics.

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

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

The description begins with a specific verb ('Return') and defines the resource ('dependency graph of change orders across every registered ComOS repo'), then enumerates the graph's components (nodes, parent/child edges, interest edges, drift reports). This clearly distinguishes it from sibling introspection tools by naming the graph-specific scope.

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

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

The description clearly implies when to use the tool—when a full dependency graph with drift reports is needed—but provides no explicit alternatives or exclusions compared to siblings like change_reach or climb_history. It gives context but not direct usage rules.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds rich behavioral detail: traverses interest and parent/child edges, includes provenance per reached artifact, provides a seeds-walked evidence chain under D8, and explains return shape alternatives. It also discloses default values for max_hops and include_parent_child, which is not in 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 and front-loaded with the core purpose, but it runs on as a single long sentence that could be broken into clearer segments. Every clause adds useful information (defaults, return types, examples), so there is minimal waste, but readability would benefit from structural separation.

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

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

Given the tool's complexity (graph traversal, provenance, evidence chains) and the absence of an output schema, the description is highly complete: it specifies parameters with defaults, return shape ({kind: 'evidenced', value, chain} or {kind: 'no_evidence_available', reason}), and traversal semantics. The agent should be able to use this tool correctly without further documentation.

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

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

With 0% schema coverage, the description fully compensates by explaining each parameter: origin_slug is the CO directory slug with an example, max_hops bounds traversal depth with default 1, and include_parent_child toggles decomposition tree reach with default true. It also explains the return value meanings tied to the 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 with a specific verb and resource: 'Return the REACH of a change' across all registered repos, traversing the change-graph's interest and parent/child edges. It distinguishes itself from sibling introspection tools like change_graph or co_decisions by focusing on reach and provenance.

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

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

The description implicitly conveys when to use the tool (to find all artifacts affected by a change via graph traversal) but does not explicitly contrast it with sibling tools or provide when-not-to-use guidance. There are no stated alternatives or exclusions, leaving the decision to the agent's inference from the detailed behavior.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description only needs to add context. It does so by describing the two return shapes (evidenced vs no_evidence_available), snapshot contents, and default behavior, enriching the behavioral contract 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 a single, logically ordered paragraph covering purpose, snapshot fields, defaults, parameters, and return behavior. Every sentence adds value, and it is front-loaded with the tool's primary function.

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 and lack of an output schema, the description fully covers purpose, parameters, defaults, edge cases, and return format. The explicit mention of both success and empty/missing result kinds ensures callers know exactly what to 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?

With 0% schema description coverage, the description compensates by explaining since as an ISO timestamp, limit as an integer ≤1000, and repo as a selector for a repo subtree. It also reveals the default 200-snapshot cap, giving practical meaning not present in the raw schema.

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

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

The description specifies a time-series read of honesty-ratio snapshots and the climb trajectory, clearly distinguishing it from sibling introspection tools focused on corpus, change graphs, or other system dimensions. The verb 'read' and specific resource make the tool's purpose unambiguous.

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

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

Provides clear usage context: defaults for window/repo, parameter syntax, and when it returns no_evidence_available. It does not explicitly compare with alternative tools or state when not to use it, so it stops short of a 5.

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

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

The annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context by explaining the two possible return shapes ({kind: 'evidenced'} or {kind: 'no_evidence_available'}) and the data fields included, which goes beyond what annotations provide.

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

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

The description is information-dense but not unnecessarily verbose. The core purpose is front-loaded, and the mode breakdown is clear. The trailing 'Added by CO...' sentence is extraneous for an AI agent evaluating tool usage, so it loses a point for including non-functional metadata.

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

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

Given no output schema, the description adequately explains return values and their structure. It covers all three parameters, their modes, and the type of data returned, making the tool fully understandable for an agent to select and invoke it correctly. The annotations handle safety, so no further context is needed.

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

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

Schema description coverage is 0%, so the description must compensate, and it does thoroughly. It explains the meaning and purpose of each parameter: mode with its three enum values, co_id associated with 'touched_co', and agent_id associated with 'agent_autonomous'. This gives full semantic meaning beyond the bare schema.

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

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

The description clearly states the tool queries the CO-management decision log and specifies exactly what it returns: every change-order operation an agent scored or actuated, as an evidenced graph node. It distinguishes from siblings by focusing on 'CO decisions' and detailing the evidence structure (confidence breakdown, threshold, outcome, accountability, PR link).

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

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

The description provides explicit guidance on when to use each mode: 'touched_co' with co_id, 'agent_autonomous' with agent_id, and 'escalated'. This gives clear use-case context. However, it does not mention alternatives or when not to use this tool, so it stops short of the highest rating.

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 exact response schema ({kind: 'evidenced', value, chain} or {kind: 'no_evidence_available', reason}), accepted node kinds and ID forms, and the optional repo scope. This is rich behavioral context and does not contradict the safe-read flags. No annotation contradiction.

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

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

Two sentences, front-loaded with the primary action, and every phrase adds value (confidence range, evidence chain, node kinds, ID forms, repo scope, response shapes, valid ID source). No fluff or repetition.

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

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

The description covers return types, parameter semantics, and a key prerequisite. However, it does not explain the meaning of 'Phase A' or the behavior when given an invalid node ID (only says valid IDs come from list_nodes). Given the lack of an output schema, the response shape is well explained, but a bit more edge-case context would make it complete.

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

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

With 0% schema description coverage, the description compensates by explaining the meaning of node_kind (artifact | tool | tenant), node_id (path | name | id), and repo (scopes to one repo's corpus). While the enum already lists node_kind values, the node_id format and repo semantics go beyond what the schema provides.

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

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

The description opens with a specific verb ('Return') and a clear resource ('confidence number for a federation node'), includes the output range and evidence chain. It enumerates node kinds and ID formats, and clarifies the response shape with two possible kinds. This is distinct from sibling tools like introspection_system_list_nodes (listing) and introspection_system_probe (probing).

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 notes that valid node IDs come from introspection_system_list_nodes, providing a prerequisite. It also explains the optional `repo` scopes to one repo's corpus. However, it does not explicitly contrast with alternative tools or state when not to use this tool, so it does not earn a 5.

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

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

Annotations already declare read-only and idempotent behavior. The description adds valuable behavioral context by specifying the return contract ({kind: 'evidenced', value: Gap[], chain} or {kind: 'no_evidence_available', reason}) and clarifying the conditional scope parameter. This goes beyond what annotations provide.

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

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

Two sentences with no redundancy. The first sentence front-loads the core purpose; the second packs parameter constraints and return shape efficiently. Every word earns its place.

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