ComOS Federation Gateway

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 beyond those annotations by specifying it 'returns composed knowledge' and 'performs no transaction,' reinforcing the read-only nature without contradicting any structured data.

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 long, front-loads the action ('Read About ComOS'), and contains no redundant or filler content. Every word 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?

For a zero-parameter, read-only knowledge tool without an output schema, the description fully covers purpose, behavior, and usage context. There are no gaps given the tool's simplicity.

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

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

The tool has zero parameters, so parameter-level explanation is unnecessary. The baseline of 4 applies; the description appropriately focuses on behavior rather than parameters.

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

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

The description explicitly states the tool 'Read[s] About ComOS — the Federation User Manual's knowledge,' using a specific verb and resource. It clarifies the scope ('About ComOS', 'comos-federation voice') and distinguishes it from sibling knowledge tools like 'how_to_about'.

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

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

The description implies usage when the agent needs knowledge about ComOS, but it does not explicitly state when to use it over alternatives such as 'how_to_about' or 'federation_help'. No exclusionary guidance is provided.

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

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

Annotations already mark destructiveHint=true, but the description goes further by disclosing hard limits (5 sends/day, 2000 chars, no attachments), side effects (journaled receipt as the state delta), and caller restrictions (cohort roots only). It also explains the sender identity and the CO 245 policy. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: purpose, identity, restriction, limits, journaling behavior, and policy. It is front-loaded with the action and avoids fluff. Despite being multi-sentence, it is concise for the complexity covered.

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 authorization, rate limits, content constraints, side effects, and policy. It mentions the receipt but does not explicitly state the return value or error handling. Given no output schema, the tool does a strong job, but a minor gap remains regarding what the caller sees directly.

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 add meaning beyond the schema for parameters. The schema already documents 'to' as a real counterparty, body constraints, and optional reply_to. The description reinforces these points but adds no new parameter semantics, so baseline 3 applies.

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

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

The description opens with a specific verb and resource ('Send one outbound email') and clarifies its unique role as the rail for contacting a REAL external counterparty. This distinguishes it clearly from all sibling tools, none of which handle outbound email. The identity and scope are explicit.

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 to use this tool ('the rail for contacting a REAL external counterparty') and imposes authorization boundaries (restricted to cohort roots). It does not explicitly name alternatives or exclusions, but the niche is clear enough given the sibling list. Policy guidance (CO 245) adds appropriate context for content.

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 well beyond the annotations (readOnlyHint=false, destructiveHint=true) by disclosing the global impact ('affects every tenant'), the self-admission restriction, and the audit trail ('recorded with attribution', 'preserves the gate's original reasoning'). This adds valuable behavioral context that annotations alone 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 compact and front-loaded: it states the action first, then the critical permission and impact. Every sentence adds value (purpose, restriction, attribution, reason), with 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 decision tool with no output schema, this description fully covers prerequisites (root manager), the decision options (admit/exclude), side effects (affects reputation, attribution), and edge cases (cannot admit itself). It is complete for an agent to safely invoke the tool.

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

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

Schema description coverage is 100% and every parameter already has a clear description in the schema. The description adds no new parameter semantics beyond repeating what's in the schema (e.g., certifications ignored on excluded). Baseline 3 is appropriate since 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 tool's action: 'Render the operator verdict on an under-review admittance application (CO 344): admit or exclude.' It specifies the resource (admittance application) and the verb (decide/render verdict). This distinguishes it from siblings like federation_admittance_queue (which lists applications) and federation_apply (which creates them).

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

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

The description gives explicit context: 'FEDERATION ROOT MANAGER ONLY' and explains consequences ('admitting a sender affects every tenant'), including a when-not ('a manager cannot admit itself'). However, it does not explicitly name alternative tools or say when to use this instead of others, 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?

Beyond the readOnlyHint/destructiveHint annotations, it discloses important behaviors: return order (oldest-first), the critical need to check the 'truncated' flag to avoid mistaking a partial queue for an empty one, and the required permission (managers:admin). This is meaningful behavioral context.

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

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

Two sentences plus a warning and permission note. Every sentence provides value, front-loaded with the core purpose, and 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?

The tool is simple (one parameter, read-only, no output schema), and the description covers the essential aspects: what it reads, ordering, truncation warning, and permission. It's complete for its complexity.

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

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

The input schema fully describes the 'platform' parameter with an example, and the description mentions it in passing but doesn't add extra semantics beyond what's in the schema. With 100% schema coverage, 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 uses a specific verb ('Read') and resource ('applications awaiting an operator decision on a platform'), clearly distinguishing it from the sibling 'federation_admittance_decide' which handles decisions. The reference to CO 344 adds 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 clearly states when to use this tool (to read pending applications for operator review) but doesn't explicitly mention alternatives like 'federation_admittance_decide' as the complementary action. The context is clear enough that an agent could infer usage.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable context beyond annotations: it specifies the authentication mechanism (OAuth JWT) and required scope (agents:read). It does not explain return format or behavior, but for a read-only status endpoint, the added auth context is sufficient.

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

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

The description is relatively short (3 sentences) but includes an unnecessary and confusing sentence: 'agentId comes from federation_list_agents.' This adds noise given that agentId is not a parameter. The first two sentences are useful, but the third reduces clarity and conciseness.

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

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

For a simple one-parameter tool with no output schema, the description adequately covers authentication and scope. However, it does not explain what the status response contains, and the unwarranted mention of agentId creates ambiguity about whether the tool supports filtering by agent. This inconsistency is a gap in 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?

The schema describes auth_token as 'JWT auth token for authentication' with 100% coverage. The description enriches this by clarifying it is a 'federation OAuth access token (JWT)' and specifying the required scope 'agents:read'. This adds meaning beyond the schema. The extraneous agentId reference does not detract from the auth_token clarification.

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: 'Get current status of all agents and the scheduler.' This is a specific verb ('Get') and resource ('current status of all agents and the scheduler'), and it distinguishes itself from siblings like federation_list_agents (which lists agents) and federation_get_agent_runs (which gets run history).

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

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

The description provides guidance on authentication ('Requires authentication via auth_token') and required scope ('requires agents:read'), which is useful. However, it does not explicitly state when to use this tool versus alternatives, and the mention of 'agentId comes from federation_list_agents' is confusing since no agentId parameter exists in the schema, potentially misleading usage.

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

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

The description goes far beyond the annotations by disclosing side effects: 'your manager root is minted, bound to the email your token carries,' the fact that a tokenless call never admits, the cost structure (6% buy, 3% sale), and ongoing governance enforcement (CO 259). This fully discloses behavioral traits, with no contradiction to readOnlyHint=false and destructiveHint=false.

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

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

The description is front-loaded with the core purpose, then methodically explains token behavior, prerequisites, costs, and governance. Every sentence contributes useful information—no filler—and the structure is logical despite being longer than typical descriptions.

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 dual behavior, no output schema, and significant side effects, the description covers all essential context: the two modes, the offer URLs, cost implications, and post-join governance. It does not state return values, but the behavior is so clearly defined that an agent can infer what to expect. The description is 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?

Schema descriptions cover 100% of parameters, so information like email binding and applicant_name meaning is already in the schema. The description adds some context about the OAuth token (not a schema parameter) and the two modes, but it does not significantly enhance individual parameter meaning beyond the schema. Baseline 3 is appropriate given 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 tool's function: 'Join the ComOS network as a vendor' and distinguishes two modes—admission when called with an OAuth token versus merely recording a contact request when tokenless. It specifies the resource affected (manager root minted, bound to token email) and stands apart from siblings like federation_admittance_decide and federation_create_manager.

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 for when to use the tool: 'Called with your OAuth token, this ADMITS you' and 'Called without a token, it records a contact request only.' It also directs the agent to read the offer first (/.well-known/comos-vendor.json or /offer.md) and clarifies that no human review or charge applies, giving clear context for tokenized vs. tokenless 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds meaningful context about the score derivation (trust-weighted, ComOS-signed counters, not raw volume) and clarifies it is a 'fact surfaced, not a verdict rendered', which aids interpretation.

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

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

Three dense sentences, front-loaded with the core purpose, and no filler. The figurative language ('a fact surfaced, not a verdict rendered') earns its place by adding interpretive nuance.

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, filtering modes, and relationship to catalogs. Since no output schema exists, it could more explicitly describe the return format, but the description gives enough to infer a ranked list. The limit parameter is left to the 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 covers all three params at 100%, so baseline is 3. The description adds the 'Omit args' guidance for the default top-of-board view, which clarifies default behavior beyond the schema. Other param references mostly echo schema descriptions.

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

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

Clearly states it is a live arena ranking agent-run businesses by settlement-signed reputation. It specifies the core function (ranking) and differentiates from catalog tools by noting 'the catalog is how you enter; the arena is how you're ranked.'

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 patterns: omit args for top of board, use platform= to filter by vendor type, tenant_id= for one business's rank. Names sibling tools and explains the relationship, giving clear when-to-use 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?

The description discloses significant behavioral details (decay lifts in ~30s, no review, identity from token), but these details contradict the readOnlyHint=true annotation. The description clearly indicates a state-changing effect (healing decay), which violates the read-only hint. 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?

The description is efficiently structured with three sentences, each adding essential context: what it does, when to use it, and what it cannot do. It is dense but not bloated, and 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?

Despite having no parameters and no output schema, the description comprehensively covers the tool's behavior, timing, exclusions, and identity source. It fully explains the self-healing mechanism and the operator freeze exception, making the tool's usage complete.

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

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

The tool has zero parameters and schema coverage is 100% (empty schema). Per guidelines, a 0-param tool gets a baseline 4; the description adds no parameter info needed.

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

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

The description clearly states the tool's purpose: to attest the manager root is alive, tying it to a specific mandate (CO 264). It also distinguishes this explicit attestation from implicit attestation via privileged actions, making the tool's unique role unmistakable.

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

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

Provides explicit when-to-use guidance (when idle or to self-heal a mandate-decayed root) and when-not-to-use (an explicit operator freeze is NOT lifted). This is strong, actionable guidance that helps the agent decide when to invoke the tool.

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

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

Annotations only mark readOnlyHint=false and destructiveHint=false, but the description adds substantial behavioral detail: funds stay on the ledger, nothing crosses, no cut is taken, the bond is a published fact, and release requires ACTIVE standing. It also discloses the required OAuth scope, going well beyond the structured annotations.

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

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

The description is front-loaded with the core action and is dense with useful information. While slightly verbose with metaphorical phrasing like 'no cut bites' and the cryptic 'CO 265', every sentence serves a purpose—covering effect, optionality, release constraints, and authorization.

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 isn't required to explain return values. It covers prerequisites (owning the treasury, OAuth scope), the effect, optionality, and a key release constraint. For a two-parameter tool with fully documented schema, this is reasonably complete and actionable.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by noting that amounts accumulate on an existing bond and that tenant_id must reference a treasury you own. This reinforces and extends the schema's parameter descriptions with operational nuance.

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 ('Post (or increase)') and identifies the exact resource ('your manager root's bond') and mechanism (moving spendable to bonded). It clearly distinguishes this tool from siblings like federation_bond_release and federation_bond_status by focusing on the posting action and referencing the published fact for counterparties.

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 optionality ('never required at the door') and gives operational context such as ownership of the treasury and the OAuth scope. It does not explicitly name alternatives or provide 'when not to use' exclusions, but the distinction from release/status is implied through 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?

The description reveals extensive behavior beyond annotations: the two-step notice clock, reset condition, requirement for ACTIVE standing, and the exact consequence (illiquidity while in bad standing). It also states the required OAuth scope (tenants:write). This goes well beyond the bare readOnlyHint/destructiveHint flags and does not contradict 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 dense sentences, front-loaded with the primary action. Every clause carries meaningful information: the call flow, the clock, the standing requirement, the consequences, and the auth requirement. 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?

For a zero-parameter tool with no output schema, the description explains the process thoroughly, including failure modes and consequences. It doesn't specify the exact return value after each call, but the two-step state machine is fully described. Slight gap on the response shape, but overall complete enough for an agent to invoke correctly.

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

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

The tool has zero parameters and schema coverage is 100% (vacuous). The baseline for zero params is 4. The description adds no parameter docs, but none are needed. It does add contextual semantics around the stateful process, which is more relevant than params here.

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 a specific verb + resource: "Release your bond (CO 265)". This clearly distinguishes it from sibling tools like federation_bond_status and federation_bond_post, and the scope is explicit.

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 step-by-step usage: first call starts the clock, second completes at maturity, with conditions (standing must be ACTIVE, transitions restart the clock). It doesn't explicitly name alternatives or when NOT to use, but the context is clear and excludes common pitfalls (no forfeit, no reviewer).

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 valuable context: the bond is a 'public machine-legible fact' and it mentions the default behavior of reading your own bond. No contradictions; this exceeds the baseline by explaining semantics beyond safety 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 sentences, front-loaded with the primary action, and every word contributes. It conveys the resource, content, legal reference, and a usage hint without padding.

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, the description lists the return fields (amount, state, notice maturity, standing-fact block) and notes the public nature, making it fully self-contained. No output schema exists, but the description sufficiently covers 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?

The schema has 100% coverage for the single parameter, but the description adds a useful behavioral note: 'Omit manager_id to read your own' which clarifies the default. This enriches understanding beyond the schema's 'defaults to the caller' by being actionable guidance.

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 ('Read') and identifies a precise resource: a manager root's bond, listing exact fields (amount, state, notice maturity). It also distinguishes itself from sibling tools like federation_bond_post and federation_bond_release by focusing on the read 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 gives clear context: it reads a manager's bond, and explicitly instructs to omit manager_id to read your own. While it doesn't name alternative tools for when to use them, the read-only nature is self-evident from the verb and is reinforced by sibling names, providing enough context.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description discloses the behavior of the `source` field, the prerequisite that a put refuses until the store row exists, and the auth requirement. This is valuable, non-redundant context that helps the agent understand side effects and conditions.

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 long, front-loaded with the core purpose, and each sentence adds distinct value: what it does, how it differs, and key behavioral caveats. There is no redundant content.

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

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

Given a single simple parameter and no output schema, the description provides sufficient information for correct invocation: it defines the resource, the return context (raw canon and source field), the admin auth requirement, and the interaction with put. This is 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 schema already provides 100% coverage with a clear description for tenant_id, so the description need not add much. The tool description does include 'tenant' in context, but it doesn't elaborate on format or examples beyond what the schema gives, aligning with the baseline for full 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 tool reads a tenant's RAW knowledge canon from the compose_inputs store, using a specific verb and resource. It also distinguishes itself from the flattened markdown tool and references federation_canon_put, 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?

The description implies when to use this tool by contrasting RAW canon with flattened markdown served by another tool, and it notes the admin requirement and dependency on put. However, it doesn't explicitly name the alternative tool or provide a direct 'use this when...' versus 'use that when...' statement, leaving a small gap.

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), the description discloses critical behaviors: the tool only edits existing rows (boot seed owns creation), refuses empty document sets, serves new text in the next request without deploy/restart, requires managers:admin, requires confirm to equal tenant_id, and warns about fixture reseeding. This substantially exceeds the annotations' minimal signal.

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

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

The description is dense but every sentence carries load-bearing information: purpose, replaced/append mode, scope constraints, failure conditions, propagation behavior, auth, confirmation requirement, and fixture warning. It is well-structured with clear labeling (e.g., 'WHOLE-CANON REPLACE', '⚠️') and remains focused.

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

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

For a destructive, whole-canon write tool, the description covers all key operational aspects: what it writes, what it cannot touch, row-edit semantics, empty-set refusal, propagation timing, auth, confirmation guard, and the fixture side-effect. No output schema exists, but the description prioritizes the effect and constraints, which is what an agent needs for correct invocation.

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

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

The schema already provides detailed descriptions for all 4 parameters (100% coverage), including the confirm echo and the full replacement requirement. The description adds context like the whole-canon semantics and the fixture warning, which supplements but does not replace the schema. Baseline 3 is elevated by this extra guidance.

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 'Replace a tenant's knowledge canon in the compose_inputs store' with the explicit qualifier 'WHOLE-CANON REPLACE'. This distinguishes it from read tools like federation_canon_get and from delta updates, making the tool's purpose unambiguous.

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

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

The description gives strong usage guidance: 'send every document, not a delta' and 'knowledge-only by construction... edits existing rows only'. It implies when-not (not for delta, not for non-knowledge changes) but does not explicitly name alternative tools. The context is clear enough for correct selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, lowering the burden. The description adds behavioral context beyond the schema by specifying that omitting all args returns the fleet 'grouped by who-it-serves and by platform' and that agent=<slug> yields a 'full card.' This clarifies default behavior without contradicting annotations.

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

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

Three sentences with no filler: purpose, usage modes, and a sibling pairing note. Every sentence earns its place and the most important information is front-loaded. Perfectly concise for the functionality described.

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 no output schema, so the description does a good job describing what the agent will get for each invocation mode (grouped fleet, filtered, single card). It doesn't mention edge cases like pagination or exact return format, but for a catalog browser with rich sibling context, this is sufficient. It also helps disambiguate from the many sibling tools by naming federation_catalog_platforms.

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 value by explaining how the three parameters combine: omitting yields grouped output, serving as a filter, and agent selects a single card. While the schema describes each parameter individually, the description clarifies the default/combined semantics for all 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 ('Browse the ComOS network's autonomous agent fleet') and clearly states what the tool provides ('what each agent does and who it serves'). It distinguishes itself from federation_catalog_platforms by explaining that agents are 'operators you hire' versus 'platforms what you become.'

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 alternatives are provided: 'Pairs with federation_catalog_platforms' and a conceptual distinction between agents and platforms. The description also gives concrete usage modes: omit args for grouped fleet, pass serves= or platform= to filter, or agent=<slug> for a full card. This tells the agent exactly when and how to use the tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral detail: the call is recursive, returns label/posture/availability/replaces/tagline at every depth, and is designed to serve both human navigation and agent shopping. It also clarifies the parent parameter changes the level, which is a non-obvious traversal 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 six sentences, each delivering distinct value: purpose, side semantics, parent semantics, recursive behavior, return payload, and sibling relationship. No filler or tautology.

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 no output schema and only two parameters, so this description carries the burden. It fully explains navigation modes, traversal semantics, and return fields, and even references the companion tool. This is complete for an agent to select and invoke correctly.

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

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

The schema already includes descriptions for both side and parent (100% coverage), but the description adds interpretive examples: side='vendor' returns sell-on platforms like retail and bookings; parent='messaging' descends into email/sms/dm. These make the enum and string semantics concrete beyond the schema.

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

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

Description opens with a specific verb 'Browse' and identifies the resource 'ComOS network's composable platforms' as a recursive catalog. It distinguishes itself from sibling federation_catalog_agents by explaining platforms are 'what you become' versus agents as 'operators you hire.'

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 maps side values to sell-on vs run-with contexts and instructs when to omit side. It also explains parent usage with a concrete example and notes that side is ignored when parent is present. Additionally, it pairs with federation_catalog_agents and explains the relationship, giving the agent clear decision criteria.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds that it is a public read with optional auth_token. It also clarifies the grouping behavior (collapses variants into one row per family with price range) and that the limit applies before grouping, which adds 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?

Three sentences total, front-loaded with the key purpose, then usage guidance, then practical sourcing info. 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?

Given a read-only search tool with no output schema, the description sufficiently explains the purpose, grouping behavior, alternatives, and tenant_ids sourcing. It could be more specific about the exact response format, but that's not required for a list/search tool and the schema covers the inputs.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description adds value by explaining the grouping semantics (limit is per tenant before grouping) and provides the source of tenant_ids, but it doesn't add much 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 searches product FAMILIES across multiple tenants in parallel, collapsing variants into one row per family with price range and option breakdown. It distinguishes itself from the sibling federation_catalog_search_multi by explicitly saying '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?

The description says 'Prefer this for discovery' and explicitly points to the alternative when exact SKUs are needed, naming federation_catalog_search_multi. It also tells where tenant_ids come from (federation_list_tenants or pass 'all') and notes auth_token is optional.

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 useful context: 'Public read — auth_token is optional' and that search runs 'in parallel'. These details go beyond the annotations and help set expectations about authentication and performance, though not exhaustive (e.g., no mention of response format 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?

Three sentences with no filler. The core action is first, followed by usage guidance and a reference to a sibling. Every sentence adds unique information, 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?

Given the tool's 5 parameters, no output schema, and rich sibling set, the description covers the essential context: what it does, how tenant_ids work, when to use an alternative, and auth expectations. This is more than sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so all parameters are already described. The description adds extra meaning for tenant_ids by explaining the 'all' literal and pointing to the source (federation_list_tenants), which is valuable on top of the schema. No other parameters need clarification.

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

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

The description states a specific verb ('Search'), a clear resource ('products'), and a distinguishing scope ('across multiple tenants in parallel'). It also explicitly contrasts itself with the sibling tool 'federation_catalog_search_grouped_multi', 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 when-to-use guidance: 'Use federation_catalog_search_grouped_multi for browse/discovery flows to get token-efficient family rollups.' It also tells the user where tenant_ids come from ('from federation_list_tenants') and clarifies the 'all' option, giving full context for selection.

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

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

The annotations declare readOnlyHint and destructiveHint, and the description adds behavioral nuance: it is a 'cheap' operation, returns a fingerprint to be compared, and warns about consequences of acting on stale data. This goes beyond the safety hints to explain the operational meaning of the result and its role in the catalog-change detection workflow.

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, starting with what it does, then how to use it, then why it matters. There is no filler; each sentence adds critical operational context.

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

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

Given the tool's simplicity—one parameter, no output schema—the description fully covers the return value's meaning and usage. It explains how to interpret the catalog_version and what action to take on mismatch, which is more than sufficient for a version-check 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 fully describes the single parameter tenant_id with 100% coverage, so the description doesn't need to add much. The description references 'a tenant' in the first line, but otherwise relies on the schema. This meets the baseline for fully documented 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 returns a catalog fingerprint for a tenant, using a specific verb and resource. It distinguishes itself from sibling search tools by framing itself as a cheap freshness check rather than a full catalog read. The phrase 'compare the returned catalog_version against the one embedded in your previous catalog_search result' explicitly ties its purpose to search results.

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

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

The description provides explicit when-to-use guidance: check the version before acting on catalog data, and if it differs, re-run catalog_search to get current product_ids. It even gives a concrete precaution against referencing stale SKUs. This directly addresses alternatives by directing to catalog_search when a refresh is needed.

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=true), the description discloses key behavioral traits: returns a 'FACT-ONLY organic_rank', a 'SEPARATE, disclosed promotion label slot (never a rank input)', and an 'eliminated block showing who was dropped and on which clause.' It also explains that constraints 'ELIMINATES non-qualifying tenants', giving a transparent picture of how filters and ranking work. This adds substantial context 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 a single, dense paragraph that front-loads the main purpose and then flows logically through inputs, outputs, and usage. It is longer than average but every sentence contributes necessary detail for a four-parameter, multi-behavior tool. Minor deductions for a slightly rambling structure; it could be split into clearer sections, but it remains 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?

With no output schema, the description thoroughly explains the return structure: qualifying candidates, fact-only organic rank, separately labeled promotion slot, and eliminated block. It covers all parameters, describes the two candidate scoping modes, and gives usage context. For a tool of this complexity, the description is fully sufficient to guide correct invocation.

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

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

Although the schema has 100% parameter description coverage, the description adds concrete examples for constraints (e.g., '{dimension:"geo",op:"includes",value:"NG"}') and clarifies the candidates object structure with distinct modes. This is especially valuable because the constraints schema uses an empty `items: {}`, so the description fills a critical gap in understanding param formats.

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

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

The description opens with a specific verb and resource: 'Compare federation tenants on their structured choice_profiles to pick one for a need.' This clearly distinguishes it from sibling tools like catalog search or choice_get by focusing on comparison and selection against a need. It also states the exact purpose without ambiguity.

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

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

The description explicitly says 'Use this to choose a tenant before buying via the catalog/order path.' It further explains when to use each candidates mode: '{tenant_ids:[...]} after a catalog search' or '{discover:true, vertical?} to find candidates by need.' This provides clear contextual guidance and implicitly contrasts with search or order tools.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral detail by specifying the return payload (full choice_profile, freshness, separate promotion label with null when not promoted), which goes beyond the annotations and clarifies expected output semantics.

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 action, and every phrase adds information about purpose, content, or usage context. There is 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?

For a simple read-only tool with one parameter and strong annotations, the description provides sufficient context: what is fetched, the composition of the choice_profile, freshness, promotion label semantics, and usage trigger. It does not cover error behavior for non-existent tenants, but given the tool's simplicity and the presence of annotations, 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?

Schema description coverage is 100% for the single parameter tenant_id, with the schema already stating 'The tenant whose profile to fetch'. The description adds minimal extra meaning—only that it fetches 'one tenant's' profile, which is largely contextual. Per rubric, baseline is 3 because the schema carries the parameter documentation burden.

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 ('Fetch') and resource ('one tenant's full choice_profile'), and elaborates on what that includes (organic comparable facts, per-vertical attributes, freshness, promotion label). It also distinguishes itself from the sibling tool federation_choice_compare by stating it is used after comparison has narrowed to 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?

The description provides explicit usage context: 'Use after federation_choice_compare has narrowed to a single tenant and you want everything it published.' This clearly indicates when to use the tool, though it does not mention alternative tools or scenarios where it should not be used, stopping short of a full when/when-not specification.

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 reveals significant behavioral details beyond annotations: the call is an accountability-root write gated by managers:admin, minting is free, admission is via OAuth proof-of-control of email, and the trust model is structural rather than identity-based. It also cites governance enforcement as a control, which is valuable context absent from 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 includes a substantial amount of design rationale ('Binding accountability, not verifying identity, is the design') and many CO references that are not directly needed for invoking the tool. The essential operational guidance is present but buried among philosophical context, making it less concise than it could be.

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

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

The description covers purpose, prerequisites, scope requirements, cost, and downstream workflow, which is comprehensive for a complex tool without an output schema. It doesn't describe the return value or response shape, which is a minor gap given the tool's complexity, but the description still provides a strong operational picture.

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 meaningful context for email (OAuth admission) but doesn't systematically explain role, handle, or other parameters beyond what the schema already provides. The schema carries the primary 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 opens with 'Mint a manager — the accountability root that owns tenants (CO 138 / CO 159)', clearly identifying the action and resource. It distinguishes the tool from siblings by positioning manager creation as the root step before 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?

The description provides explicit workflow guidance: 'Next: create tenants with federation_create_tenant, then compose a platform by entering it' and lists required scope (managers:admin) plus non-root gating. It doesn't explicitly state when not to use the tool, but the context and alternatives are clear enough.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description adds critical behavior: 'Requires the tenants:write scope', 'Provisions the spine only', the optional manager_handle behavior, and the explicit refusal handling: 'the result is a typed, legible refusal naming the gate — never a silent failure'. This richly discloses 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 a single, dense paragraph with each sentence contributed a distinct piece of information: purpose, scope, auth, parameter guidance, and error behavior. No redundancy, 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?

Given six parameters and no output schema, the description covers purpose, partial provisioning, authentication, parameter-specific behavior, and failure semantics. It is complete enough for an agent to correctly invoke the tool without requiring external 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 the baseline is 3. The description adds extra value for manager_handle ('Pass manager_handle to hang the tenant under your accountability root — omitted, the tenant is created without an owning manager') and composed_platforms ('Valid composed_platforms names come from federation_catalog_platforms'), elevating it above baseline.

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

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

The description clearly states the tool's primary function: 'Create a new tenant (CO 138 — the federation gateway owns the manager/tenant lifecycle)'. It specifies the resource (tenant) and verb (create), and differentiates from siblings like federation_create_manager and federation_delete_tenant by adding 'Provisions the spine only; platform substrate is provisioned on platform-admit'.

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 usage context: it requires the 'tenants:write' scope, references sibling federation_catalog_platforms for valid composed_platforms names, and alludes to the complementary step 'platform substrate is provisioned on platform-admit'. It does not explicitly state 'use this instead of X', but the context is sufficient to know when to use it.

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

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

Annotations already declare destructiveHint=true, but the description adds substantial behavioral disclosure: irreversibility, no undo/export, which specific rows are destroyed, authorization nuances (operator can call, machine identity cannot), and the feature-flag gate. This exceeds what annotations alone provide and aligns with 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?

Every sentence delivers specific operational value: the warning is front-loaded, the alternative comparison is compact, and no filler exists. Even though it's longer than average, the density of useful information justifies 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?

The description covers the tool's effect, the exact data destroyed, alternative tool usage, required auth scope, caller restrictions, refusal cases, feature gate, and absence of undo/export. For an irreversible destructive action, this is exceptionally complete, and no output schema exists to explain return values.

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

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

Schema description coverage is 100% for both handle and confirm, but the description adds crucial semantic weight by emphasizing that `confirm` must exactly equal `handle` and is 'the only guard' against irreversible deletion. This reinforces the parameter's lifecycle-critical role beyond the schema's basic description.

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

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

The description opens with 'IRREVERSIBLY delete a tenant' and enumerates the exact destroyed data (registry row, composition/manager-link rows, entire per-tenant database). It clearly distinguishes this from federation_suspend_tenant by contrasting suspend's status flip with delete's data destruction.

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

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

Explicitly names the alternative (federation_suspend_tenant) and explains when delete is appropriate vs. suspend. It also states required scope (managers:admin), operator vs. machine identity restriction, refusal for shared infrastructure, and the FEDERATION_OWNS_LIFECYCLE gate, giving precise 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?

Annotations only declare readOnlyHint=true and destructiveHint=false. The description goes far beyond this by disclosing session persistence via mcp-session-id, 24h idle expiry, the authoritative reply structure (platform_tools, composed_tool_defs), the REST twin behavior, and the resumption/re-scoping semantics. This is rich behavioral context with no contradiction.

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

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

The description is long but every sentence earns its place: purpose, workflow, reply structure, session mechanics, REST twin, and info-tenant exception are all packed densely. It is front-loaded with the core purpose and organized logically, so the 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?

Despite having no output schema and sparse annotations, the description provides a complete picture: what the reply contains, how sessions work, when to re-enter, how the REST twin behaves, and the distinction for info tenants. This is more than sufficient for an agent to select and invoke this 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 fully documents tenant_id with 100% coverage. The description adds meaningful context by explaining that tenant_ids come from federation_list_tenants, giving examples ('about-us'), and showing how the tenant_id appears in the REST equivalent. This goes beyond the schema's bare definition.

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 pair: 'Enter a tenant to receive its tool surface (progressive disclosure)'. It clearly distinguishes this tool from siblings by contrasting it with federation_list_tenants and explaining that this is the tool for entering a tenant, not merely listing or inspecting them.

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

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

The description explicitly states the workflow: 'list tenants with federation_list_tenants, then enter one here'. It also provides guidance on re-entering to resume after idle expiry, re-scoping on re-entry, and notes that info tenants serve read-only knowledge directly on tools/list, giving practical when-to-use 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 indicate destructiveHint=true and readOnlyHint=false. The description adds meaningful context beyond annotations: 'Enforced at dispatch' explains the timing of the effect, 'its graph cannot take privileged actions' specifies the impact, and 'managers:admin' discloses an authorization requirement. This is slightly above 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 three concise sentences, front-loaded with the action and object. Each sentence adds distinct information: purpose, enforcement timing, reversibility and permission. No redundant or filler content.

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

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

For a simple mutation tool with no output schema, the description covers the essential context: effect, enforcement, reversibility, and permission. It does not describe the return value, but that is not strictly necessary for this operation. The description is adequate given 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?

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds a little value by mentioning the effect of 'standing' and 'manager root', but this mostly restates what the schema already conveys. 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 ('Freeze'), names the resource ('manager root'), and states the effect ('set its standing to frozen or suspended so its graph cannot take privileged actions'). It clearly distinguishes from the sibling tool 'federation_unfreeze_manager' by explicitly naming it as the reversible counterpart.

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

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

The description implies when to use the tool (to freeze a manager root) and explicitly points to the alternative for reversal ('Reversible via federation_unfreeze_manager'). It also notes the required permission ('managers:admin'), giving clear context. It does not explicitly state 'when not to use', but the scope is well-enough defined.

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 detailing the auth token requirements (OAuth JWT, agents:read scope) and the composed run behavior for Tier 2 agents. It does not contradict the annotations and gives meaningful context beyond the structured metadata.

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

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

The description is three sentences, immediately stating the core purpose and then providing essential usage details. Each sentence adds necessary information: purpose, authentication, and composed-run behavior. There is 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?

The description adequately covers purpose, authentication, and the nuanced includeComposed behavior for a read-only tool. Without an output schema, it omits details about the return format, but the title and schema parameters (limit, status) give sufficient context. It 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 schema covers all parameters (100% coverage), so the baseline is 3. The description adds meaningful context by explaining auth_token's nature and required scope, clarifying agentId's provenance, and elaborating on includeComposed's purpose (composedRunIds referencing Tier 1 runs). This goes beyond the schema's 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 action: 'Get execution history for an agent.' This uses a specific verb and resource, distinguishing it from sibling tools like federation_agent_status (current status) and federation_run_agent (executing runs). The context of agentId sourced from federation_list_agents further clarifies the tool's 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 provides clear context on authentication requirements (auth_token with agents:read scope) and identifies agentId from federation_list_agents. It also explains when to set includeComposed:true for tenant-operator agents. However, it does not explicitly name alternatives or state when not to use this tool, so it lacks explicit exclusion 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 value by clarifying that it reflects live constants, enforces what is read, and does not disclose private manager standing, which goes beyond the basic 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 a single dense paragraph with many concepts crammed together, making it somewhat difficult to parse. While it is front-loaded with 'How the federation governs its agents', it could benefit from clearer structuring or bullet points. The content is relevant but not optimally 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?

For a zero-parameter, read-only overview tool with no output schema, the description thoroughly covers the governance model, including autonomy levels, manager ceilings, thresholds, and enforcement rules. The cryptic 'CO 295' is unexplained, but overall the description provides a sufficiently complete picture for an agent to understand what the tool offers.

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 covers all inputs (100% coverage). The description does not need to add parameter details, and the baseline of 4 is appropriate since parameter semantics are fully handled by the empty schema.

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

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

The description clearly states that the tool explains 'How the federation governs its agents' and details the autonomy ladder, manager ceiling, and related governance concepts. It distinguishes itself from sibling tools by focusing on governance constants, though it lacks a crisp 'verb + resource' phrasing.

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 by noting the tool is read-only and reflects live governance constants, but it does not explicitly state when to use this tool versus alternatives or provide exclusions. It offers some context for appropriate use but lacks direct guidance.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds context about the included instructions (product IDs, authentication flow). However, it does not describe the output format or any additional behavioral specifics, so it only partially supplements the structured data.

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 and a clear imperative. No wasted words, and the structure leads with the tool's role before explaining its value.

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

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

Given the zero-parameter schema and lack of output schema, the description fully covers what an agent needs to know: what the tool does, when to use it, and why. It is complete for its simplicity.

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

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

The tool has 0 parameters, so the baseline is 4. The description does not need to elaborate on parameters, and its focus on usage instructions is sufficient for an agent to invoke the tool correctly.

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

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

The description clearly identifies the tool as the source of usage instructions for the MCP federation, using the verb 'Get' with a specific resource. It distinguishes itself from sibling federation tools by explicitly positioning it as the preliminary guide.

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 'CALL THIS FIRST' provides explicit timing guidance and implies it should precede other tools. It also highlights key content areas (product IDs, auth flow), giving clear context, though it does not state when not to use it or list 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?

Beyond the annotations (readOnly=false, destructiveHint=false), the description discloses append-only semantics, idempotency on entry_key, OAuth permission requirements (journal:write), and tenant ownership restrictions. This gives the agent critical behavioral context for safe invocation.

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 long but every sentence contributes: purpose, use case, idempotency, permissions, and ownership. It is well-structured with a clear narrative arc, though it could be tightened without losing value.

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

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

Without an output schema, the description does not detail the return value, but for an append operation that is acceptable. It covers the key behavioral aspects (idempotency, permissions, tenant scoping) and the motivation for using it, making it largely complete for the agent's needs.

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

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

Schema description coverage is 100% with detailed descriptions for all 8 parameters, so the baseline is 3. The description adds high-level context (e.g., 'entry_key' as idempotency handle) but no new per-parameter details; the schema already carries the load.

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 ('Append') and resource ('your agent journal'), and clearly distinguishes this from the sibling tool 'federation_journal_read' by focusing on the write operation. It also explains the journal's role as durable memory, making the purpose unambiguous.

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

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

The description provides clear context for when to use this tool: to record decisions and reasoning that cannot be rebuilt from federation state, so future cold sessions can resume without human recap. It also contrasts with already-durable data (identity, capital, tenants) to indicate what this tool is NOT for, though it does not explicitly name alternatives like the read 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 reinforces this with "replay" semantics. It adds behavioral context not in annotations: ordering (oldest→newest), authentication requirements (OAuth bearer with journal:read), and tenant ownership restrictions. No contradiction.

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

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

Three sentences, front-loaded with the main action. Each sentence provides distinct value: order, usage context, pairing, auth, and ownership. The "CO 230-001" reference is slightly cryptic but not distracting. Overall tight and 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-param read tool with no output schema, the description covers usage, prerequisites, constraints, and pairing. It doesn't explicitly state the return format (the journal entries), but "replay your agent journal" implies it. The guidance is sufficient 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 coverage is 100%, so both parameters (tenant_id, limit) already have descriptions. The description adds little beyond the schema, only emphasizing that only tenant_id is needed for the core action. This meets the baseline for high schema coverage but doesn't elevate 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 opens with a specific verb+resource: "Replay your agent journal oldest→newest." This clearly distinguishes it from siblings like federation_journal_append (the write counterpart) and other federation tools. The scope and direction (oldest→newest) add precision.

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

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

Explicitly says when to call: "at the start of a cold session." It names the paired tool (federation_journal_append) as the complement, implies the alternative for writing, and gives prerequisites (journal:read, manager root ownership). This is actionable guidance beyond what annotations provide.

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 reveals failure behavior ('a wrong key, an expired/absent nonce, or a tampered signature binds nothing'), the persistence of proof in a tamper-evident log, and the response receipt structure ({ seq, entry_hash, prev_hash }). It also discloses that identity is read from the token. This is extensive behavioral disclosure.

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 action, then efficiently covers prerequisites, verification, effects, and output. It is about 150 words but each sentence earns its place, with no filler. The structure makes it easy to scan.

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

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

Given the tool's complexity and the lack of an output schema, the description covers prerequisites, permission, failure modes, and the response receipt format. It even notes the external evidentiary value of the receipt. This is sufficient for an agent to invoke the tool correctly and interpret the result.

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 detailed descriptions for all three parameters, including algorithm values, signature over nonce bytes, and key formats. The description adds context about the nonce source and failure conditions, but does not significantly extend parameter semantics beyond the schema. With 100% schema coverage, a 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 opens with a clear action: 'Bind a public key to your manager root (CO 314)', specifying a precise verb and resource. It distinguishes from sibling tools by referencing the nonce from federation_key_challenge and by its role in the key lifecycle. This makes the purpose unmistakable.

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

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

It states the workflow prerequisite: the signature must be over the nonce from federation_key_challenge, and it lists the required permission ('Requires tenants:write'). It also notes that re-binding rotates the key, clarifying when the tool is used repeatedly. However, it does not explicitly name alternatives or state when not to use it.

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

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

The description adds important behavioral details beyond the annotations: the returned nonce is 'single-use' and 'short-lived', and the tool requires 'tenants:write'. It also clarifies that identity is read automatically from the token. This provides meaningful context for invocation, though it doesn't explain what happens if called multiple times or the exact nonce format.

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, each delivering necessary information: the action, the nonce and next step, and the permission requirement. Every sentence earns its place and the description 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 tool has no parameters and no output schema, so the description fully covers what an agent needs: what the tool does, what it returns, how to proceed, and the required permission. It is complete for its simplicity.

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

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

With zero parameters and 100% schema coverage, the description compensates by explaining why no parameters are needed: 'Identity is read from your token.' This clarifies that the tool is implicitly authenticated and no explicit input 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 'Begin binding a public key to your manager root (CO 314)', which clearly states the action (begin binding) and the resource (public key to manager root). It also references CO 314 and distinguishes itself from the subsequent tool 'federation_key_bind', making the purpose unambiguous.

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

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

The description implicitly explains when to use this tool: as the first step of a key-binding process, explicitly directing the user to 'present the signature to federation_key_bind'. It also notes that identity is read from the token and requires 'tenants:write', which gives usage context. However, it doesn't explicitly contrast with other key-related tools like federation_key_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 mark it as read-only and non-destructive, but the description adds valuable behavioral context: it includes the attestation chain's current head, notes that it never returns challenges or secrets, and directs to the full chain location. This goes beyond the structured annotation data.

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 a clear, front-loaded purpose, enumerate return fields, and add security-relevant caveats. No redundant or filler text; 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?

Despite lacking an output schema, the description explicitly lists the return fields (public_key, alg, kid, bound_at) and the attestation chain head. It also clarifies optional invocation and what is not returned, making the tool's behavior fully understandable in isolation.

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 single parameter manager_id is fully documented in the schema with the same information ('The root to read; defaults to the caller.'). The description's 'Omit manager_id to read your own' adds no new semantic content beyond the schema, so it meets the baseline for high coverage.

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

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

The description opens with 'Read a manager root's bound public key', a specific verb and resource, and lists exactly what is returned (public_key, alg, kid, bound_at). It clearly distinguishes itself from write tools like federation_key_bind by being a read operation, and mentions the attestation chain head, making its scope 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 context: it is used to read a key that a counterparty verifies signatures against, and explains the optional manager_id. It does not explicitly name alternative tools or exclusion conditions, but the context strongly implies when it 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 declare readOnlyHint=true and destructiveHint=false, and the description adds that values are measured from real audit records, never asserted, and that empty history returns null percentiles + sample_count 0 (an honest empty). This goes beyond the annotations by detailing the tool's behavior for edge cases and its source of truth.

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 around 90 words and is front-loaded with the core meaning. It covers purpose, usage, and edge-case behavior without waste, though the closing 'Verify, don't trust.' is a stylistic flourish rather than essential 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 tool's simplicity (two optional params, no output schema), the description covers return values (percentiles, sample_count), the empty-history case, and the live/audit source. It's sufficiently complete for an agent to use correctly.

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

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

Schema already documents both params with 100% coverage, but the description adds usage semantics: 'Omit args for the whole surface; tool= to scope to one tool; limit= to widen/narrow the sample window,' which aids understanding of how to adjust the query. This is more than a restatement, so 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 (in ms) from audit records, positioning it as the verifiable answer to latency questions. This distinguishes it from sibling tools like federation_agent_status or federation_solvency, and the verb 'measured' and resource 'recent authenticated tool executions' make the purpose unambiguous.

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

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

The description gives clear usage context: use it to verify whether latency claims (e.g., sub-100ms) are true, with instructions to omit args, use tool=, or limit= to adjust the sample. However, it does not explicitly name alternatives or exclusions, so it doesn't 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 readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: it requires auth_token with agents:read scope, calls it a federation OAuth access token, and notes the call is refused without it. This goes beyond the annotations and clarifies authentication expectations.

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 concise sentences with no redundant information. It front-loads the primary action and return values before addressing authentication, making it efficient and easy to scan.

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

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

Given that there is no output schema, the description partially explains the return values (status and next scheduled run) but does not enumerate all possible response fields. However, for a list tool with simple filters, this is sufficient for an agent to understand the tool's purpose and usage, especially with the provided authentication 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%, but the description adds meaningful semantics for the auth_token parameter by specifying it's a federation OAuth JWT and requires agents:read scope. This compensates for the schema's generic 'JWT auth token' description, though other parameters (status, agentType) rely on the already-adequate 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 ('List all configured agents') and specifies the returned information ('with their status and next scheduled run'), distinguishing it from sibling tools like federation_catalog_agents (catalog listing) and federation_agent_status (likely single-agent status).

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 for when to use the tool (listing all configured agents with status), and the authentication requirement implies a read operation. It does not explicitly name alternatives or exclusions, but the scope is well-defined and the sibling list makes differentiation obvious.

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 useful behavioral context beyond the readOnlyHint annotation by detailing the auth_token as a federation OAuth JWT and the required agents:read scope. No contradictions with annotations exist.

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

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

The description is two sentences with no redundancy: first states the action, second explains the auth parameter. It is perfectly sized and front-loaded with the core purpose.

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

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

For a simple list tool with one parameter and no output schema, the description is sufficiently complete: it covers purpose, authentication, and permission. It could hint at return format, but this is not critical 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 documents auth_token, but the description enriches it by explaining the token type (federation OAuth JWT) and required permission, adding meaning beyond the schema's generic 'JWT auth token for 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 tool lists all available agent types that can be configured, using a specific verb and resource. It distinguishes from siblings like federation_list_agents and federation_catalog_agents by focusing on 'agent types' rather than agents or catalog entries.

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 discovering configurable agent types and explicitly mentions the authentication requirement. However, it does not provide exclusion criteria or alternatives, so the guidance is limited to context rather than a full differentiation from similar tools.

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

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

Beyond the readOnlyHint annotation, the description adds that it 'surfaces only safe fields (no credentials, 2FA, or billing)' and requires 'managers:admin' permission. This provides useful behavioral context about the tool's output safety and authentication needs, exceeding what annotations alone convey.

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

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

The description is two sentences with the main action front-loaded ('List managers') followed by concise, valuable context. Every clause adds meaning—domain definition, read-only nature, safe fields, and permission—without 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, parameter-less list tool, the description covers purpose, domain meaning, safe output fields, and required permission. Since no output schema exists, the description provides sufficient high-level information about what to expect, making it complete for its complexity.

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

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

The tool has zero parameters, so the baseline for this dimension is 4. The description does not need to explain parameters, but it adds context about output fields, which is relevant to what the tool returns. No parameter coverage gap exists.

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 'List managers' and further defines managers as 'the accountability roots that own tenants (CO 132 / CO 136),' distinguishing it from sibling tools like federation_list_tenants or federation_manager_tree. The verb 'List' and resource 'managers' are specific and unambiguous.

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

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

The description implies usage when a read-only list of managers is needed and states a prerequisite ('Requires managers:admin'). However, it does not explicitly name alternative tools or describe when not to use it, so it falls short of the explicit when/when-not guidance required for a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds value beyond annotations by stating the return format ('Returns tenant IDs, names, and status') and the purpose (discovering interactable tenants), which is especially useful because there is no output schema.

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

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

The description is two sentences, front-loaded with the primary action, and contains no fluff. Every word contributes to understanding the tool's purpose, return value, and usage context.

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 list tool with no parameters, good annotations, and no output schema, the description is complete. It explains what the tool does, what it returns, and when to use it. No critical information is missing.

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

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

The tool has zero parameters, so the schema already fully covers this aspect (100% coverage). The description adds no parameter information, but none is needed. Baseline for 0 parameters is 4.

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

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

The description clearly states the tool's function: 'List all available tenants in the federation.' It specifies the verb (List), the resource (tenants), and the scope (all available in the federation). It also distinguishes itself from sibling tools like federation_tenant_info (which likely focuses on a single tenant) and federation_list_agents (which lists agents instead).

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 a clear use case: 'Use this to discover which tenants you can interact with.' This gives context on when the tool is appropriate. However, it does not explicitly mention alternatives or when not to use it, though sibling tool names imply the distinction.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds 'Read-only; requires managers:admin.' This provides a useful permission requirement beyond the annotations. However, no details about return format, pagination, or error behavior are given, and the cryptic 'CO 132 / CO 136 — the concealed-common-control surface' is not explained, leaving some behavioral ambiguity.

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 core concept, followed by scope and permission notes. The cryptic parenthetical 'CO 132 / CO 136 — the concealed-common-control surface' may obscure rather than clarify, but the overall length is appropriate and each sentence adds functional value.

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

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

For a read-only tree-listing tool with a single optional parameter and no output schema, the description covers the essential context: what it returns, how to scope, read-only nature, and required permission. It does not elaborate on edge cases or output structure, but given the simplicity and good annotations, it is reasonably complete. The unexplained internal references to CO 132/136 slightly reduce 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% with a clear description for the 'manager' parameter. The description adds the crucial detail that omitting the parameter yields the whole forest, which goes beyond the schema's 'Scope to one manager' wording. This is helpful but does not fully compensate for the lack of other behavioral specifics; a baseline 3 is appropriate given 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 identifies the tool's output: a manager→tenant accountability tree showing one manager, its tenants, and the role on each. It is distinct from sibling list tools (e.g., federation_list_tenants) by emphasizing the tree structure and scope control. However, it lacks an explicit verb like 'list' or 'get', relying on a noun phrase, which slightly weakens 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 gives practical scoping guidance ('Scope to one manager or omit for the whole forest'), making usage context clear. It does not explicitly name alternatives or state when not to use this tool, but the scoping instruction implicitly covers common decision points. No explicit when-not or alternative recommendation is provided.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description adds rich behavioral detail: pricing curves keyed on usage-to-date, free-to-start tiers, steady last-tier pricing, effective-forward repricing, and the guarantee that reads and exits are never charged. It also aligns with the read-only annotation by stating reading is discovery and never charged.

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 front-loaded with the core purpose and every sentence contributes critical pricing semantics. The trailing 'CO 287' is cryptic and adds no clear value, slightly detracting from conciseness, but overall the structure is 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?

The description is essentially complete for a zero-parameter, read-only tool with no output schema. It covers the data format, pricing rules, exceptions (reads/exits/writes), and asserts the map's authority, leaving little ambiguity about what the tool returns or how to interpret 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?

With zero parameters, the schema provides no meaning, so the description fully compensates by explaining the returned data structure: the usage-tiered curve format [[threshold, price_coms], ...], the meaning of [0,0] tiers as free-to-start, and the last tier as the steady price. This is essential for interpreting the tool's 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 this as the federation pricesheet containing per-act Com prices for every platform's tools, with an explicit note that reading is free. It distinguishes from sibling tools by focusing on pricing data rather than actions like sending, searching, or managing tenants, though the primary verb 'read' is embedded rather than stated upfront.

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 implicit usage context: consult this tool to learn prices, with 'Any tool not listed is free' and 'Reads, exits, and settling sale-path writes are never priced' indicating when pricing is irrelevant. It does not explicitly state 'use this before invoking other tools' or name alternatives, but the authoritative 'what you read is what you pay' signals when to rely on it.

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

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

Beyond annotations, the description discloses critical behavioral facts: the 'Promoted' label never alters/hides/reorders organic facts, over-cap/off-autonomy escalates to manager approval, insufficient balance returns CO 016 402, and settled promotions are irreversible. This is exceptional transparency for a mutating Com-spending operation.

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

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

Four dense sentences pack purpose, behavioral guarantees, error paths, irreversibility, and auth into a tight paragraph. Every sentence earns its place and front-loads the core action before layering safety and edge-case details.

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

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

With no output schema, the description still covers prerequisites, side effects (irreversible spend), escalation behavior, and an error code. It is comprehensive for a transaction-like tool, leaving no critical context unexplained.

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

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

The schema has 100% parameter coverage, so the baseline is 3. The description adds domain meaning: need_context is 'the buyer-need string agents pass to federation_choice_compare', spend defaults to 'per-consideration charge', and label defaults to 'Promoted'. This enriches the schema without repeating 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 opens with a specific verb+resource+target: 'Promote a tenant's choice_profile into agent consideration for a need-context'. It clearly distinguishes the tool from siblings like federation_choice_compare by positioning it as the action that creates labeled visibility, not just comparison. This uniquely identifies the tool's 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 states a clear prerequisite ('Requires managers:admin on your federation OAuth bearer (admitted via federation_apply)') and ties the need-context to federation_choice_compare. It implies when to use the tool but does not explicitly contrast it with alternatives or provide exclusions. Strong contextual guidance 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?

The description goes well beyond the minimal annotations (readOnlyHint=false, destructiveHint=false) by disclosing important behavioral traits: cache bypass, 30-second rate limiting with no-op behavior, per-instance best-effort semantics, and required OAuth scope. This provides the agent with complete safety and side-effect awareness.

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 composed of four focused sentences: the action, the use case, the rate limit, and the isolation/permission constraints. Every sentence delivers distinct, necessary information 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 tool's simplicity (no parameters, no output schema) and sparse annotations, the description is complete. It covers purpose, usage timing, rate limiting, side effects, isolation, and authentication requirements, leaving no significant gap for an agent to misuse the tool.

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

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

With zero parameters, the baseline is 4. The description adds value by clarifying that the tool takes no inputs and performs an immediate global action, which is sufficient given the empty 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 opens with a clear, specific verb+resource: 'Force the federation to re-discover its tool list from every platform'. It further distinguishes itself from siblings by explicitly mentioning the cache bypass mechanism, making its unique purpose unmistakable.

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

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

It clearly states when to use this tool: 'Use after a platform adds, removes, or changes tools and you need the change visible immediately.' While it doesn't name alternative tools explicitly, the usage context is precise and leaves no ambiguity about when this refresh 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?

The description discloses significant behavioral traits beyond annotations: the agent 'runs with its own identity and side effects,' warns that a token without the required scope is refused, and calls it an 'Operator-grade lever.' This adds meaningful context about trust and consequences, which annotations (readOnlyHint=false, destructiveHint=false) do not capture.

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

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

Three sentences, each earning its place: the action, the param source, and the auth/behavioral warning. No redundant fluff or repetition of schema details.

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

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

For a mutation trigger tool with no output schema, the description covers purpose, prerequisites, auth, side effects, and usage caution. It doesn't mention what the return value looks like or how to check run status afterward, but it is substantial enough for an agent to select and use 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% with descriptions for both parameters. The description adds extra semantic value by explaining that agentId comes from federation_list_agents and that auth_token must have the agents:admin scope, enriching the schema's simple type/description. This justifies above-baseline scoring.

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

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

The description opens with a specific action: 'Manually trigger a federation agent to run immediately.' It clearly identifies the resource (federation agent) and the verb (trigger/run), distinguishing it from sibling status/list tools like federation_agent_status or federation_list_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?

It provides clear use context: agentId comes from federation_list_agents, requires an admin-scoped JWT, and is an 'Operator-grade lever' with safety guidance ('trigger only agents you operate'). However, it doesn't explicitly name alternatives or state when not to use it, though the context strongly implies it.

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

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

The description adds significant behavioral details beyond annotations: it returns a route, not a transaction; empty routes return 'unroutable: true' with no silent default; and it's deterministic. Annotations only cover safety hints, so this is valuable 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?

Four information-dense sentences with no fluff. Each sentence earns its place: purpose, input/output, edge-case behavior, and determinism. The structure front-loads the key action.

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, so the description compensates by explaining the return: ranked platforms with per-platform next tools. It also covers the empty-route edge case and the need to act with a tenant. This is complete 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 coverage is 100%, so baseline is 3. The description enriches the 'intent' parameter with multiple examples and emphasizes it's free-text, adding meaning beyond the schema's single example. 'limit' is not mentioned in the description, but the schema already describes it adequately.

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

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

The description clearly states the verb and resource: 'Route a natural-language intent to the right platform.' It distinguishes itself from siblings by emphasizing it's the 'first thing to call' and returns a route, not a transaction.

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

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

Explicitly says it's the first step ('first thing to call') and clarifies what it does NOT do ('not a transaction'). While alternatives aren't named, the usage context is clear and provides implicit exclusions.

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

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

Beyond the readOnlyHint annotation, the description adds significant behavioral context: it is 'Computed from real GL rows, never asserted,' explains that `unbalancedEntries` are a defect even when the margin is positive, and clarifies that `solvent` requires both conditions. It also discloses the 'always free' cost trait, 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 somewhat lengthy but each sentence contributes unique information, from the field list to the defect explanation to the computation source. The opening question is engaging but not strictly necessary, and the CO references may be jargon; however, it remains well-structured and front-loaded with the core purpose.

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

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

With no output schema, the description fully documents the return values and their semantics, including the meaning of `unbalancedEntries` and the combined `solvent` condition. It also covers the data source, access characteristics, and the discovery-oriented use case, making it self-sufficient for a no-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?

The input schema is empty with zero parameters, so there is no parameter semantics to explain. The baseline score of 4 applies, and the description instead focuses on the output fields, which is appropriate given the lack of an output 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 'Returns the dollar ledger's live solvency invariant' and lists the specific fields (reserve, outstanding, margin, unbalancedEntries) and the combined `solvent` condition. It distinguishes itself from sibling tools by emphasizing its unique focus on solvency and its 'verify, don't trust' posture, while explicitly referencing federation_latency and federation_pricesheet.

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

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

The description provides clear context that this tool is used to check whether the Com float is actually backed, and it notes that it is 'Public, read-only, always free' for discovery purposes. However, it does not explicitly state when not to use it or name direct alternatives beyond referencing two siblings with a similar posture, so it lacks explicit exclusion 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 destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds valuable context about authorization (must own the tenant or be root/admin) and mentions 'federation owns the lifecycle', which goes beyond the annotations to explain behavioral constraints. The cryptic 'CO 138/222' references are not useful, but overall transparency is good.

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 front-loads the primary action. It is concise, but the inclusion of 'CO 138' and 'CO 222' introduces unexplained jargon that may reduce clarity for an agent, slightly lowering the score from ideal.

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

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

For a simple 2-parameter tool with no output schema, the description covers the core purpose, lifecycle ownership, and authorization. It does not disclose what happens when a tenant is suspended (e.g., impact on active sessions), which would be useful, but given the low complexity, the description is sufficiently 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% and both parameters (handle, suspend) have descriptive schemas. The description adds 'true → suspend, false → reactivate' only in the schema, not in the description itself, so it adds little beyond what the schema already conveys. The description's 'Suspend or reactivate' mirrors the parameter semantics without expanding 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 'Suspend or reactivate a tenant', which specifies a concrete action and resource. It differentiates from sibling tools like federation_delete_tenant by using 'suspend/reactivate' rather than 'delete', and the 'lifecycle' phrasing reinforces the distinct intent.

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 by the action (suspend/reactivate) and the caller-ownership requirement. However, there is no explicit guidance on when to choose this tool over alternatives like federation_delete_tenant, nor are exclusions or specific scenarios provided beyond the ownership note.

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 agent knows this is a safe read operation. The description adds that the result includes metadata, description, and configuration, which is useful context. However, it does not disclose behaviors such as what happens if the tenant ID is invalid, any required permissions, or the detailed return format. With annotations covering the safety profile, 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 a single sentence of 14 words, front-loaded with the action and resource, then specifying the content areas. Every word earns its place; there is no redundancy or vague filler. This is a model of conciseness.

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

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

For a simple read-only tool with one parameter, strong annotations, and a clear description of what is returned, this is largely complete. The lack of an output schema is partially offset by the mention of metadata, description, and configuration. It does not cover error handling or alternative tool comparison, but it provides enough for correct invocation in most scenarios.

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 parameter tenant_id with 100% coverage, including a description. The tool description does not add any extra meaning beyond what the schema provides, 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 action ('Get detailed information') and the target ('a specific tenant') with specific content areas (metadata, description, configuration). This clearly distinguishes it from sibling tools like federation_list_tenants (which lists many tenants) or mutation tools like federation_update_tenant. However, it does not explicitly name an alternative tool, so it falls just short of a 5.

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 'a specific tenant' implies this tool is for fetching details of a single tenant, but it does not explicitly state when to use this over federation_list_tenants or other tenant-related tools. No exclusions or alternative tool names are provided. Usage guidance is implied but not made explicit, so a score of 3 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 provide readOnlyHint=false and destructiveHint=false, and the description adds valuable context: the permission requirement (managers:admin) and the behavioral consequence (the manager's graph may take privileged actions again). No contradiction with annotations; the description enriches 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?

A single, information-dense sentence that leads with the action, includes the policy reference, notes the effect, and states the required permission. 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 2-parameter tool with good annotations, the description covers purpose, effect, and permission adequately. No output schema exists, but the description does not need to explain return values given the straightforward nature of the operation; minor added details like reversibility would improve 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 description coverage is 100%, with each parameter (manager_id, reason) already documented in the schema. The description does not add unique parameter-level detail beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

Specific verb 'Restore' with resource 'manager root' and outcome 'to active standing' clearly defines the action. The policy reference (CO 259-001) and immediate consequence ('graph may take privileged actions again') further distinguish it from sibling tools like federation_freeze_manager.

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?

Clear context that the tool is for unfreezing a manager root that was previously frozen, implying use when reactivation is needed. However, it does not explicitly state when-not-to-use or name the complementary freeze_manager as an alternative, though the sibling listing makes this obvious.

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 annotations: it explains that composing a platform makes its tools branch on enter_tenant, that unreachable platforms remain inaccessible until composed, and that CO 222 requires ownership or root/admin. This elaborates side effects and authorization, which 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 dense sentences, each adding unique value: fields, lifecycle context, composition effect, and 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?

Given the complexity of the composition behavior and no output schema, the description covers the essential aspects: update fields, permission requirements, and the reachability consequence of composition. The schema fills the parameter details, making the tool well-documented.

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 each parameter already has detailed descriptions, especially composed_platforms which explains the replace semantics, unknown platform refusal, and omit behavior. The description reinforces these points but adds little new parameter-specific meaning.

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 updates a tenant's display name, description, and/or composed platforms, which is specific and distinguishes it from sibling tools like create/delete/suspend. The mention of 'federation owns the lifecycle' adds 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 provides clear context for when to use (updating an existing tenant's attributes) and a prerequisite (caller must own tenant or be root/admin). It doesn't explicitly name alternatives, but the sibling list and update focus make the intended use 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, so the bar is lower. The description adds that the tool returns a thesis that is relayable verbatim to the human root, giving useful context about the output's nature. 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 well-structured and front-loaded with the main point. Every sentence adds value: purpose, contrast with sibling, usage context, and return content. No extraneous words, and the thesis summary is succinct yet 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?

The tool is simple (0 parameters, no output schema), and the description fully covers its return value and usage context. It explains what 'whys' are addressed, who it's for, and what the output consists of. No gaps remain.

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 0 parameters, so the baseline is 4. The description does not need to add parameter details, and it doesn't. It adds no parameter info, but the schema is empty and coverage is 100%, so a score of 4 is appropriate.

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

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

The description clearly identifies the tool's purpose: it returns the thesis for why to build on ComOS, using a specific verb ('Returns') and resource ('the thesis'). It also distinguishes itself from the sibling tool federation_help by contrasting HOW vs. WHY.

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

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

Explicitly states when to use ('Read this if you... are deciding whether to invest a few Coms to stand up a business') and explicitly names an alternative (federation_help tells you HOW, this tells you WHY). This is clear usage guidance with exclusions and alternates.

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

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

The description explicitly states 'Read-only — returns composed knowledge, performs no transaction,' which reinforces the readOnlyHint and adds the return type ('composed knowledge') and stylistic 'comos-federation voice.' This provides context beyond annotations 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?

At roughly 19 words, the description is extremely concise and front-loaded. It leads with the action ('Read') and resource, followed by necessary behavioral notes. Each word earns its place, with no fluff.

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

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

Given the tool's simplicity (zero parameters, read-only knowledge retrieval), the description is complete. It states the purpose, the read-only nature, and the return type. The output schema doesn't exist, but the description sufficiently conveys what the user gets—composed knowledge.

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

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

The input schema has zero parameters, so the description has no parameter explanations to add. With no parameters, the baseline score of 4 applies—the description appropriately doesn't need to elaborate on parameter behavior.

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

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

The description clearly identifies the tool as reading 'How to use ComOS' — the operational walkthrough's knowledge. It specifies the exact resource and distinguishes it from siblings like federation_help by focusing on the ComOS usage guide. However, it doesn't explicitly contrast with alternatives, so it's not a perfect 5.

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 tool is for retrieving how-to-use-ComOS knowledge, but it does not state when to use this tool versus alternatives like federation_help or about_us_about. There are no explicit usage scenarios or exclusions, making guidance minimal.

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 safety profile is known. The description adds important behavioral detail: any non-'current' id returns uncited(out_of_scope) rather than an error, and it explains the versioning context. This goes beyond the structured annotations.

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

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

The description is three sentences: a clear purpose statement, a key constraint with behavior, and a future note. Every sentence earns its place with 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?

Given the tool's simplicity (2 params, no output schema, strong annotations), the description covers the main usage constraint and the special return behavior. It is complete enough for a v1 sanity-check surface, though it does not describe the return format for valid usage.

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

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

Schema coverage is 0%, so the description carries the burden. It explains that the only valid value for both parameters is the literal string 'current' and describes the behavior for invalid ids. This provides meaningful semantic guidance beyond the bare parameter names.

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

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

The description opens with 'Compare two corpora by id,' which is a specific verb and resource. It clearly distinguishes from sibling tools like introspection_corpus_query by focusing on comparison rather than querying.

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

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

The description clearly states that in v1 only the id 'current' is exposed and should be passed for both sides to sanity-check the surface. It sets expectations for valid usage, though it does not explicitly name alternative tools or provide 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?

The description goes well beyond the annotations (readOnlyHint=false, idempotentHint=false) by disclosing the exact output file path, that it never admits to the manifest, the gate requirement, and the required permission. This paints a clear picture 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?

Three sentences packed with useful information and front-loaded with the main action. Some cryptic jargon like 'P-b-D gate in comai-plan' could confuse, but the description is not padded or overly long.

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 generation side effects and permissions, but it does not explain what the tool call returns to the caller (e.g., success status, file contents). With no output schema, this missing piece keeps it from being fully complete.

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

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

Schema description coverage is 0%, so the description carries the burden. It explains `repo` as an optional style/distribution source, but `prompt` is only implicitly defined as the generation instruction. No detail on prompt format or expected content beyond basic length constraints.

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 clearly that the tool generates a passage in the style/distribution of the corpus, with a specific verb and resource. It also differentiates from sibling tools like introspection_corpus_query and introspection_corpus_compare by emphasizing generation and file output.

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

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

Provides clear context for when to use: it requires a specific OAuth permission, outputs to a review file, and optionally targets a single repo. It does not explicitly name alternatives but the sibling tools are obviously distinct.

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 the description adds useful scope context (intra-repo vs. future cross-repo). However, it does not disclose return format, output behavior, or any additional side effects beyond what the annotation implies. No contradiction with annotations exists.

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

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

The description is two sentences with the main purpose front-loaded. It earns its place, though the editorial phrase 'Highly load-bearing for honest epistemic surfacing' and the 'Phase 3.5' version reference add minor noise without core 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 simple read-only introspection tool with two parameters and no output schema, the description adequately conveys purpose and scope. It lacks details about the shape of the returned disagreement data, but the simplicity of the tool and the read-only annotation make this an acceptable level of 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 description coverage is 0%, so the description must compensate. It explains that 'topic' is the subject of disagreement and that optional 'repo' restricts to intra-repo disagreement, but it does not describe topic formatting, constraints, or the precise meaning of a repo identifier beyond the phrase.

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 ('Ask') and names a clear resource ('the corpus where its artifacts disagree on a topic'), making the tool's function immediately obvious. It also distinguishes itself from sibling introspection tools like introspection_corpus_query or introspection_corpus_compare by focusing specifically on disagreement.

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

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

The description implies when to use the tool (when you want to find disagreement among corpus artifacts) and explains the optional repo scope, but it does not explicitly mention alternatives, exclusions, or when not to use this tool. This is only implied, not 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?

The description adds valuable behavioral details beyond the readOnlyHint annotation: it specifies that the tool returns a topical map with citations, or uncited(out_of_scope) when the topic is not covered. It also mentions the optional repo scoping behavior. No contradictions with the annotations.

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

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

The description is two sentences with no fluff. The main action is front-loaded, and both sentences earn their place: the first states purpose and result, the second explains the optional parameter. Very concise and well structured.

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

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

The tool is simple (2 params, no output schema). The description covers the core functionality and return behavior, and mentions the optional repo scoping. It does not detail the exact structure of the 'topical map' or potential error conditions, but given the simplicity and the readOnlyHint, this is nearly complete. A 4 reflects that a bit more context (e.g., about the format of citations) could be added.

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

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

With 0% schema_description_coverage, the description carries the full burden for parameter meaning. It explains 'topic' via the main purpose sentence and explicitly describes 'repo' as an optional scoping parameter ('Optional `repo` scopes the question to one repo'). This is sufficient though not exhaustive, warranting a 4 rather than a 5.

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

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

The description clearly states a specific verb and resource ('Ask the corpus what it covers on a given topic') and explains the return type (topical map with citations or out_of_scope). It is unambiguous but does not explicitly distinguish itself from sibling tools like introspection_corpus_query or introspection_corpus_compare.

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 for when to use the tool: to ask about corpus coverage on a topic. It also mentions the optional 'repo' scoping for single-repo questions. However, it lacks explicit exclusion criteria or comparisons to alternative tools, so it does not reach level 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 readOnlyHint=true, and the description adds meaningful behavioral context: the two possible return kinds, the pinned manifest resolution, and the substring verification for content_excerpt. This goes beyond the annotation baseline and helps set expectations for reliability.

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 long, front-loaded with the core action, and every sentence adds unique value: purpose, return format, verification guarantee, and repo filter. No redundant or filler content.

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

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

With no output schema, the description compensates by explaining the return structure (cited vs uncited) and key verification behavior. It does not cover error cases or usage timing, but given the read-only nature and simple parameter set, it is reasonably complete.

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

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

The schema has zero descriptions for its two parameters (0% coverage). The description explains the repo parameter's filtering effect and implicitly defines the question parameter via the tool's purpose, but it does not give examples or clarify what constitutes a well-formed question, leaving some ambiguity.

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 its purpose from sibling tools like generate or compare by describing the cited/uncited return types. It is immediately obvious what this tool does.

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

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

No guidance is provided on when to use this tool versus the many sibling introspection tools, nor are any alternatives or exclusions mentioned. The description only says what the tool does, not when to choose it.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds critical behavioral details: 'Never silently reconciles drift' and the exact return envelope ({kind: "evidenced", ...} or {kind: "no_evidence_available", ...}). This goes beyond the structured annotations and clarifies the tool's non-mutating, evidence-based nature.

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

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

The core description is front-loaded with the action and is dense with useful details, but the trailing 'Added by comai-plan CO 013-003 / federation CO 006' does not help an agent select or invoke the tool and is extraneous. The first sentence is also a run-on, making it slightly harder 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?

Despite having no output schema, the description fully specifies what the tool returns: nodes, parent/child edges (with sources), interest edges, drift reports, and the two possible return kinds. It also clarifies the scope (every registered ComOS repo) and the non-reconciliation behavior. This is complete 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?

The tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameters, but it does add value by explaining the graph's content and return types, which compensates for the empty input schema and lack of output 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 opens with a specific verb+resource ('Return the dependency graph of change orders across every registered ComOS repo') and elaborates on nodes, edges, drift reports, and return types. This clearly differentiates it from sibling tools like introspection_system_list_nodes or introspection_system_diff, which focus on other aspects.

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

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

The description provides clear context: it covers all registered ComOS repos and explicitly states it does not silently reconcile drift, making it suitable for read-only inspection. However, it does not name alternative tools or say when not to use it, stopping 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 declare readOnlyHint and idempotentHint, and the description adds substantial behavioral detail: traversal algorithm, provenance data, evidence chain under D8, and exact return shapes. This goes far beyond the structured metadata and gives the agent a clear mental model of the tool's operation.

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

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

The description is dense but well-organized, with three sentences covering purpose, behavior/provenance, and parameters/returns. Every clause adds value; no filler or redundancy. It is 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?

With no output schema, the description explicitly enumerates the possible return types ({kind: 'evidenced', value, chain} or {kind: 'no_evidence_available', reason}). It also covers traversal rules, defaults, and provenance details, making the tool's full behavior understandable without additional context.

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

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

Schema description coverage is 0%, so the description must compensate, and it does excellently. It explains origin_slug (CO directory slug with example), max_hops (default and purpose), and include_parent_child (default and toggle behavior). This fully decodes every parameter beyond the raw schema.

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

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

The description clearly states the tool returns the 'REACH of a change' across all registered repos, specifying traversal over interest and parent/child edges. This distinguishes it from sibling tools like introspection_system_change_graph or list_nodes by focusing on impact analysis with provenance and evidence chains.

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 for when to use this tool (change impact analysis) and explains key parameters like max_hops and include_parent_child. However, it does not explicitly name alternative tools or state when not to use this tool, though the uniqueness of the reach computation makes the intent fairly obvious.

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 substantial behavioral context beyond the readOnlyHint and idempotentHint annotations, including the exact return payload structure, the no-evidence case with reasons, and the repo subtree behavior. However, the 'max 200 snapshots' statement conflicts with the schema's limit maximum of 1000, introducing ambiguity about the actual cap.

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 efficient and front-loaded, starting with the essential purpose and then detailing parameters and return values without extraneous words. The structure is somewhat dense but logical, with each sentence contributing meaningful information.

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

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

For a read-only tool with no output schema and optional parameters, the description is largely complete: it covers defaults, return formats for both success and no-evidence cases, and the repo scoping behavior. The main gaps are the unexplained 'chain' field in the return object and the ambiguity around the snapshot limit.

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 is the only source of parameter meaning. It provides minimal information: since is an ISO timestamp, limit is an integer ≤1000, and repo defaults to comai-plan. It explains repo override and implies limit relates to snapshot count, but does not explicitly state that since filters the start time or that limit caps the number of returned snapshots, leaving some gaps.

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 a time-series read of the federation's honesty-ratio snapshots, specifying the exact data returned (snapshots, decomposition counts, per-unit states). It distinguishes itself from sibling tools like introspection_system_change_graph or introspection_system_diff by focusing on climb history rather than changes or diffs.

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 usage context, stating the default window (last 7 days), default repo (comai-plan), and how to override the repo. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or complementary tools, 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?

Annotations already declare readOnlyHint and idempotentHint, and the description adds behavioral context by detailing the returned data structure (confidence breakdown, threshold, outcome, accountability, PR link) and possible return kinds. No contradiction with annotations.

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

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

The description is dense but every sentence adds value: purpose, modes, return format, and provenance. It is not overly long for the complexity, though it could be slightly better structured with separators for readability.

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

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

No output schema is present, so the description must explain return values and does so clearly with two possible shapes. It also covers all three modes and associated parameters, making it complete for a query 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 0% schema description coverage, the description fully compensates by explaining what each mode does and which parameter (co_id, agent_id) applies, plus no extra param for 'escalated'. This adds meaning beyond the enum and required field.

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

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

The description clearly states the tool queries the CO-management decision log, with specific modes and output structures. It distinguishes itself from sibling tools by focusing on decision log for change operations, with evidence and accountability details.

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 mode-based usage: 'touched_co' with co_id, 'agent_autonomous' with agent_id, and 'escalated' for waiting items. It gives clear context for when to use each mode, but does not explicitly mention alternatives or exclusions relative to other introspection tools.

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

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

Building on the readOnlyHint and idempotentHint annotations, the description adds meaningful behavioral detail: it describes the two possible response kinds (evidenced vs no_evidence_available), the presence of an evidence chain, and the meaning of the returned confidence value. This goes well beyond the annotations and clarifies edge cases like missing evidence.

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 long with no redundant phrasing. It front-loads the primary purpose, then concisely defines parameters, and finally explains the response format. Every sentence adds essential information without wasting 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, the description covers all necessary context: purpose, parameter semantics, output structure, the no-evidence fallback, and a pointer to a related tool for valid IDs. No output schema exists, so the description's breakdown of the response is especially valuable and complete.

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

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

Schema description coverage is 0%, so the description fully compensates by explaining each parameter: node_kind is given its enum values, node_id is described as 'path | name | id', and repo is described as an optional scope. It also clarifies the source of valid node IDs, adding practical guidance beyond the raw schema definitions.

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 ('Return') and a specific resource ('confidence number for a federation node') along with the output shape ('evidence chain'). It distinguishes itself from sibling tools like introspection_system_list_nodes and introspection_system_probe by focusing on confidence scoring.

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 guidance on usage context (when to call), including the prerequisite that valid node IDs come from introspection_system_list_nodes and the optional 'repo' parameter for scoping. It does not explicitly mention exclusions or alternative tools, but the context is strong enough for an agent to decide when to use it.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description does not contradict them. It adds transparency about the return contract, describing both the 'evidenced' and 'no_evidence_available' result shapes, which is useful 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?

Two sentences convey purpose, parameter constraints, and return types with no filler. It is front-loaded with the action and resource, making every word earn its place.

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