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

Even with readOnlyHint/idempotentHint annotations, the description adds meaningful behavioral context: 'Pure local math — no network, no submission' and describes output structure (ranked leaks, severity, findings, recommendations, estimated impact).

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 serves a purpose: purpose, checks performed, output details, and safety caveat. It is front-loaded and well organized for a complex analysis tool.

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 output schema exists, the description need not detail return values, but it still covers what checks are performed, output type (ranked list with severity/findings/recommendations), and the local/no-submission behavior, making it complete.

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

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

Schema already documents the 'text' parameter at 100% coverage, so baseline is 3. The description adds value by specifying 'JSON or 4 whitespace numbers' and noting it accepts the same format as rank_paste, clarifying the expected input forms.

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 ('Analyzes your token cascade and diagnoses where you're leaking efficiency') and names the resource. It distinguishes from siblings by positioning it as the pre-simulation diagnostic and referencing rank_paste's input format.

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

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

Explicit usage guidance: 'Use this BEFORE simulate_change to understand what's wrong, then use simulate_change to test fixes.' This clearly tells the agent when to invoke this tool relative to alternatives.

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

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

Annotations already mark readOnly=truehol, and the description adds key behavioral facts: it relies on the enrolled device identity and requires enrollment, and explicitly states no codename is needed. This goes beyond the annotation by clarifying a prerequisite and identity source, though it does not discuss side effects (which are minimal for a read 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?

Well-structured with clear numbered categories and a usage note, but slightly longer than necessary. Each section adds content (mentor/peer/complementary explanations), yet the level of detail could be trimmed without losing meaning. Still earns credit for front-loading the core purpose and providing terse category definitions.

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 (three output categories, identity-based logic), the description is thorough: it explains the rank-tier logic, what each category contains, the enrollment dependency, and returns are implied by the description. This covers all aspects an agent needs to invoke it correctly, and the output schema can handle details.

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 already fully cover both parameters (n with default/range, platform with default behavior). The description adds that the operator's identity is auto-detected, but this is context for the overall tool, not a parameter-specific clarification. Since schema coverage is 100%, baseline is 3; no extra value is added.

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

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

Clear, specific verb ('discovers') and resource ('mentors, peers, and complementary operators on the SigRank leaderboard'), with three enumerated categories that sharply distinguish from sibling tools like rank_paste or diagnose_cascade. Scope is explicit 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?

Provides explicit when-to-use instruction ('after submit_verification') and a recommended follow-up chain ('then chain into self_improvement with the mentor's pillar deltas as context'). This gives the agent a concrete decision path and eliminates guesswork about tool ordering.

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 behavioral traits beyond annotations: it generates a local ed25519 keypair, sends only the public key, implies agreement to terms. Annotations already indicate idempotent and non-destructive, but the description adds meaningful context.

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

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

The description is concise (3 sentences) and front-loaded with purpose, followed by instructions. Every sentence adds value 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 the tool's simplicity and the presence of an output schema, the description adequately covers the workflow and side effects. It could mention what happens after successful enrollment (e.g., confirmation), but the schema likely handles 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 coverage is 100%, so parameter descriptions already exist. The description adds value by explaining the code format (SIGR-XXXXX-XXXXX-XXXXX) and where to get it, and clarifying the default for device_label.

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

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

The description clearly states the action 'Bind THIS device to your SigRank operator' with a specific verb and resource. It distinguishes this enrollment action from sibling tools like tokenpull_submit, which are unrelated.

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 step-by-step instructions on how to obtain the key and what happens on first run. However, it does not explicitly state when not to use the tool or mention alternatives, though none are obvious given the sibling list.

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

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

Annotations provide readOnlyHint=true and openWorldHint=false, but the description adds significant behavioral context that is not already captured: the data is 'live' and 'public', results are 'sorted by yield', the exact metric formulas (Υ = Cache Reads × Output / Input²) are given, and the empty-array behavior when no operators have submitted is disclosed. This goes well beyond the annotations.

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

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

The description is detailed but every sentence serves a purpose: it explains the resource, the sort order, the return fields, the edge case, and provides usage and exclusions. The structure is logical and front-loaded with the core action, followed by details and alternatives. No unnecessary filler.

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

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

Despite having an output schema (indicated by context signals), the description still thoroughly explains all returned fields (codename, yield, leverage ratio, velocity, class tier, rank) and the empty-array behavior. This makes the tool's behavior fully understandable even without inspecting the output schema, covering all necessary context for a zero-parameter read-only tool.

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

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

The tool has zero parameters, so the baseline is 4. The description and schema both confirm that it takes no parameters and always fetches the full leaderboard. Since there are no parameters to explain, this score 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 explicitly states 'Fetches the live public SigRank leaderboard from signalaf.com' with a specific verb and resource. It also distinguishes itself from the sibling tool get_operator by noting that get_operator should be used for single-operator profiles. This is a clear, specific purpose that differentiates from alternatives.

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

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

Provides explicit when-to-use guidance: 'Use this to see where operators stand overall, to find specific codenames for get_operator lookups, or to display the current rankings.' It also gives a clear when-not-to-use instruction: 'Do NOT use this to check your own rank if you already know your codename — use get_operator instead.' This is exemplary usage 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 the description adds meaningful behavioral context: reads live submission data from signalaf.com, returns an error if codename not found, and describes the detailed profile contents. 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?

Description is front-loaded with the core purpose and contains useful usage and follow-up guidance. Slightly redundant with schema (error on not found, case-insensitivity), but each sentence earns its place by adding 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?

For a single-parameter read-only lookup tool with an output schema and annotations, the description is complete: it covers purpose, source, scope, error case, alternative tool, and downstream action. No significant gaps.

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

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

Schema coverage is 100% and the codename parameter is already well-described with case-insensitivity, error behavior, and how to discover valid values. The description adds public-visibility context but does not materially go 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+resource: 'Fetches one operator's live profile from the SigRank board by their codename.' It clearly differentiates from sibling get_leaderboard by explicitly scoping to a single operator and listing the returned metrics.

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

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

Provides explicit usage guidance: use to look up any operator who has submitted, do not use to browse all operators (use get_leaderboard instead), and mentions simulate_change as a follow-up. This is strong when-to-use and when-not-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 declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds meaningful behavior beyond that: computation happens locally 'through token-cascade,' and importantly 'No data is submitted or persisted,' plus the rule that unavailable cache telemetry stays null. These are real behavioral facts the annotations do not 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?

Four front-loaded sentences with little waste; the core action comes first and the privacy note closes it. The Upsilon/SigRank clarification sentence is arguably expendable but does aid disambiguation.

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?

An output schema exists, so return values needn't be explained, and the description covers what is computed, the local-computation model, and the no-persistence guarantee. For a tool with an output schema and full parameter documentation, this is close to complete; only the missing usage routing is a gap.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters, giving a baseline of 3. The description restates that input/output are required and that missing cache telemetry stays null, which is slightly redundant with the schema but confirms the null semantics. No additional syntax or format detail is added.

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 gives a specific verb and resource: 'Build Upsilon's portable sigrank/0.1-draft compatibility record from available token telemetry,' and names the concrete outputs (Yield, Leverage, Velocity, SNR, 10xDEV). It even disambiguates the two named products (Upsilon vs SigRank), which helps an agent orient. It lacks explicit differentiation from the many siblings, but the core purpose is unambiguous.

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

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

There is no when-to-use or when-not-to-use guidance, and no alternative is named despite a large sibling set (rank_paste, diagnose_cascade, tokenpull, tokscale_breakdown, etc.). The agent must infer the trigger condition from the purpose statement alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds crucial context beyond annotations: 'runs the full cascade math locally (no network calls)', 'deterministic prose' (idempotency), and error behavior ('Returns an error if the input is malformed or has negative values'). It also discloses the exact metric formulas and stage classification, making the tool's behavior fully transparent. No contradiction with annotations.

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

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

The description is long but densely packed without fluff. It is front-loaded with the core purpose, then systematically covers outputs, input formats, error conditions, and usage guidance. Every sentence adds information, though it could arguably be trimmed slightly; however, for a tool with this complexity and the need to distinguish from siblings, the length is justified. The structure is logical and scannable.

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 the tool's complexity, the description is entirely self-contained. It covers purpose, usage boundaries, input syntax, output semantics, error handling, local computation, and integration with submit_paste. The output schema is present, yet the description still explains each return field (yield, snr, etc.) and even the classification stages. With one parameter and no nested objects, this is more than complete—it is exceptionally thorough.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema. It explains both accepted input formats in detail, specifies the order of numbers, clarifies that values must be non-negative integers, and provides a concrete example: '{"input":1000000,"output":500000,"cacheCreate":50000,"cacheRead":800000}'. It also links the parameters to the output metrics (e.g., yield formula), giving the agent a deeper understanding than the schema alone.

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

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

The description opens with a specific verb+resource: 'Computes the SigRank yield cascade from a paste of token counts.' It clearly distinguishes from siblings by explicitly naming submit_paste and rank_windows as alternatives, and describes the precise outputs (yield, snr, leverage, velocity, dev10x, class, mode, prose card). This leaves no ambiguity about what the 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?

The description explicitly states when to use ('Use this for a quick one-off ranking without submitting to the board') and when not to use it, naming two alternatives: 'Do NOT use this to submit your score — use submit_paste instead' and 'Do NOT use this if you want to rank all four time windows at once — use rank_windows for that.' It also advises calling submit_paste afterward to publish. This is exemplary usage guidance with concrete exclusions and alternatives.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, openWorldHint=false), and the description adds real behavioral context beyond them: each window is parsed and scored independently, positional order is unsafe because dashboards list cache_read before cache_create, and windows may be omitted for partial input. It stops short of describing how malformed pastes or conflicting windows are handled.

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 purpose and output set are front-loaded in the first sentence, with routing, input constraints, and the non-submission caveat following in focused clauses. It is dense but nearly every clause carries distinct routing or correctness information; slightly long but not padded.

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?

An output schema exists, so return values legitimately need not be explained. The description covers source formats, per-window independence, key requirements, partial-input tolerance, and the submission boundary, which is everything an agent needs to call this read-only tool correctly.

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

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

Schema coverage is 100%, so the four window strings and source_tool enum are documented. The description still adds value beyond the schema by specifying the required named keys (input/output/cacheCreate/cacheRead), warning that positional order is not safe, and pointing to the WINDOWED_PROFILES gotcha.

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

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

States a specific verb (rank) and resource (all four time windows 7d/30d/90d/all-time) and names the sources (ccusage, tokscale, Claude Max dashboard) plus the outputs produced (cascade: Υ, SNR, Leverage, Velocity, 10xDEV, class, card). An agent can distinguish it from siblings like rank_paste and tokscale_breakdown without opening any schema.

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

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

Explicitly states what it does NOT do (does not submit to the board) and routes to the correct alternatives with conditions: tokenpull_submit for a local zero-paste preview, submit_verified to publish via the enrolled-device path. It also clarifies partial input (1-4 windows) is allowed and named keys are required, leaving nothing to inference.

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 readOnlyHint and idempotentHint. The description adds significant behavioral context beyond these: it details the internal steps, notes that if `text` is omitted it "runs tokenpull first (requires local ccusage logs)", and explicitly states "Pure local math — no network, no submission." It also clarifies scope behavior (daily never leaves machine; weekly distribution appears in report artifacts). This fully discloses safety and data handling.

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

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

The description is lengthy but every sentence carries information. It uses a numbered step list to structure the pipeline, which aids readability. It could be slightly tightened (e.g., the scope explanation repeats some schema content), but overall 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 a 5-step pipeline, 3 parameters, output schema present, and annotations available, the description covers the full usage context: when to call, what happens under different input conditions, scope variations, return value (cycle of diagnosis + suggestions + simulated impact), and safety highlights. It leaves no major gaps 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?

Schema coverage is 100%, so baseline is 3. The description adds extra meaning for `text` (conditional skipping of tokenpull, requires local logs when omitted) and for `scope` (adds mode detection and scoped analysis options). It does not add new details for `window` beyond the schema, but the added conditions for the other two params raise 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 opens with a specific verb+resource: "Runs the full self-improvement cycle in one call" and then enumerates the exact pipeline steps (gets pillars, diagnoses, generates suggestions, simulates, returns results). It clearly distinguishes itself from sibling tools that perform individual steps (tokenpull, diagnose_cascade, suggest_improvements, simulate_change) by branding itself as the "one-click optimize" orchestrator.

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 when-to-use guidance: "call it at the end of a session to see what to improve next time." It also explains conditional usage based on input: if `text` is provided, tokenpull is skipped; if omitted, tokenpull runs and requires local ccusage logs. It even notes the `scope` options and their implications. While it doesn't explicitly list when NOT to use it, the guidance is clear and actionable.

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

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true), the description discloses key behavioral traits: it runs the canonical cascade on BOTH current and simulated values, returns an exact yield delta (implying deterministic math), and specifically notes 'no network, no submission, pure local math.' This adds meaningful context about what the tool does and does not do.

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

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

The description is front-loaded with the core purpose, then explains the use case, and finally details the input format. Every sentence earns its place: it explains what the tool does, why to use it, and how to use it. The length is justified given the tool's complexity, and there is no filler.

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

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

The description covers the tool's purpose, inputs, outputs (yield delta, class change, per-metric diffs), and constraints (local, read-only, no submission). It also includes a practical example use case. Given the presence of an output schema and a clear input schema, the description is complete enough for an agent to decide when and how to 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?

The schema already provides full descriptions for both parameters (100% coverage). The description adds value by clarifying that the input format is 'same as rank_paste', giving explicit examples for relative deltas ('{cacheRead: '+50000'}') and absolute values ('{input: 800000}'), and restating the semantics of omitted pillars. This reinforces the schema without being redundant.

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 'what if I changed my token mix?' simulation that computes yield deltas, class changes, and per-metric diffs. It uses a specific verb ('simulate') and resource ('token mix'), and explicitly distinguishes itself from siblings as 'the first PRESCRIPTIVE SigRank tool' and a 'show me the payoff before I do the work' primitive.

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 it ('before you change your workflow') and provides a concrete example question ('would increasing my cache-read by 50k tokens actually move my class?'). It also signals when not to use it: 'no network, no submission' and 'pure local math', implying it is for analysis only. However, it does not explicitly name alternative sibling tools, so it falls short of a full 5.

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

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

Annotations already assert readOnlyHint and idempotentHint, and the description is fully consistent with that while adding real context: it does not publish, and the board's ingest endpoint now requires an authenticated Supabase session that MCP tools do not carry. This explains the behavior rather than just restating the safety flag.

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?

Longer than average but front-loaded with the critical preview-only constraint and the routing rules that matter most. Every sentence carries routing or behavioral value; only mild trimming of the endpoint detail would be possible without losing meaning.

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

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

The tool has an output schema, so return values needn't be explained, and the description still names the cascade fields produced. Combined with the strong routing guidance and the preview-only clarification, an agent has everything needed to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents both text and codename, including the JSON and whitespace-separated formats. The description adds no parameter detail beyond the schema, making 3 the correct 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?

States a specific verb and resource ('Ranks a paste of token counts locally') and immediately resolves the naming trap by declaring it PREVIEW-ONLY rather than a submission. It names the cascade outputs (yield, leverage, velocity, class, card), so the agent knows exactly what the tool produces.

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

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

Gives explicit when-to-use ('when you have token counts from ccusage or a dashboard') and two explicit when-not rules with named alternatives: tokenpull_submit for the zero-paste flow and rank_windows for multi-window pastes. It also points to submit_verified and the web UI for actual publishing.

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 idempotentHint=true and destructiveHint=false, but the description goes far beyond: it reveals the full workflow (reads pillars, builds Schema 1.0 snapshot, signs with device key, POSTs), the security property ('private key never leaves your machine'), and the dry_run capability. This adds substantial behavioral context not inferable from annotations alone. 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 a single dense paragraph that conveys multiple key facts efficiently: local source, verified operator, signing method, requirement, security note, and dry_run option. While it's slightly long, every sentence contributes meaning. It could be split into two for readability, but the structure is acceptable and front-loads the primary purpose.

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

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

Given the tool's complexity (signing, local processing, multiple steps), the description covers all critical aspects: prerequisites, workflow, security, dry_run, and the local-only nature. The output schema likely describes the return payload, so return values need not be explained. This is comprehensive for an agent to decide 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 input schema has 100% description coverage for all three parameters (window, dry_run, platform), each with its own description. The tool description reinforces dry_run specifically ('Pass dry_run:true to inspect the exact signed payload without publishing') but does not add new meaning for window or platform beyond what the schema already provides. This meets the baseline of 3 for high schema coverage; the description adds minimal extra value.

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

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

The description clearly states the tool's purpose: 'Publish your LOCAL token runs to the SigRank board as a VERIFIED operator'. It specifies the action (publish), resource (SigRank board), and distinguishes it from siblings like submit_paste or tokenpull_submit by emphasizing the verified/enrolled path. The mention of 'enrolled, signed path' and 'Requires npx sigrank-mcp enroll first' clearly differentiates this from alternative submission tools.

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

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

The description provides clear usage context: it requires an enrolled device and is the verified/signed submission path. It also mentions dry_run for testing. However, it does not explicitly state when NOT to use this tool or name alternative tools (e.g., 'use submit_paste for unverified submissions'). The prerequisite is explicit, but exclusions and alternatives are only implicit.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, but the description adds significant behavioral context beyond these: 'Pure local math — no network, no submission.' It also describes the internal simulation and ranking process, and the output structure. 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: it starts with a concise summary of the tool's purpose, then details the process and output, and ends with usage guidance. It is informative but slightly verbose; a few sentences could be trimmed without losing 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 complexity, the description is remarkably complete. It covers the input format, the improvement strategies tested, the simulation engine, the ranking by Υ yield, the output details, and the usage sequence relative to sibling tools. The presence of an output schema (not shown) reduces the burden on the description, but the description still provides ample 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% with one property 'text' described as 'Token pillars — ccusage JSON or "input output cacheCreate cacheRead" (same format as rank_paste).' The description adds value by clarifying it requires the 4 pillars and explaining the format, thus going beyond the schema alone.

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

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

The description explicitly states it generates ranked simulated improvement suggestions for a token cascade. It specifies the input (4 pillars), the process (multiple strategies, simulation with canonical cascade engine), and the output (ranked suggestions including best_single_change). It distinguishes itself from siblings by referencing the sequence: use after diagnose_cascade and before simulate_change.

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

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

The description provides clear usage context: 'Use this after diagnose_cascade to get actionable next steps, then use simulate_change to fine-tune before committing.' It also notes the tool accepts the same input formats as rank_paste. However, it does not explicitly state when not to use it or list alternatives beyond the referenced siblings.

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

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

Annotations already declare readOnlyHint=true, lowering the bar, but the description adds meaningful behavioral disclosure beyond it: data scoping ('reads usage counts not message content'), privacy guarantees ('stay on your machine unless you submit them'), and explicit data-quality caveats ('estimated=true when cacheCreate isn't available', 'dataGap note when the log format doesn't expose raw token counts'). No contradiction with the readOnlyHint annotation exists — 'pull' and 'reads' align with it.

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

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

Four sentences, each earning its place: purpose+windows, scope/cascade, privacy, and data-caveats. The structure front-loads the core purpose and moves outward to caveats. Loses one point for density in the final sentence, which crams estimated, cacheCreate, and dataGap into a single long clause that could be restructured 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?

For a single-optional-param tool with a readOnlyHint and output schema present, the description covers all essential ground: what it does, what data it touches, privacy implications, and how results may degrade across platforms. The output schema handles return-value documentation, and the description rounds out the user-facing intent (rank windows with cascade, zero paste). Nothing material is left unexplained.

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

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

Schema coverage is 100% with the platform enum fully documented (path for devin, env var for copilot), so the baseline is 3. The description adds value by explaining what the values return in imperfect conditions ('estimated=true when cacheCreate isn't available', 'dataGap note'), which helps the agent interpret results for any platform choice, and flags platform quirks ('codex is estimated via io_ratio'). Slightly above baseline but doesn't over-perform given the schema already carries the detailed per-platform 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 uses a specific verb+resource construction ('Pull your LOCAL token usage from the platform's session logs') combined with distinctive scope ('rank it across the four windows (7d/30d/90d/all-time)', 'cascade', 'zero paste') that differentiates it from siblings like rank_paste and tokenpull_compare. 'Token-only: reads usage counts not message content' sharpens the boundaries further. The resource, action, and scope are 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 context for when this tool is appropriate: it's the local, offline, privacy-preserving read operation ('zero paste', 'The numbers stay on your machine unless you submit them'), which contrasts implicitly with paste-based siblings. It doesn't name explicit alternatives like tokenpull_compare or rank_windows, but the local/paste-free framing plus setup caveats ('Some platforms need setup') provide solid contextual guidance for an agent choosing tools.

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

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

The description adds critical context beyond the readOnlyHint: it promises parallel execution, returns 'delta % vs tokenpull as the baseline', computes cascade metrics for each source, and emphasizes it is 'Token-only, on-device'. The readOnlyHint aligns with the non-destructive read nature described, and the openWorldHint aligns with the fixed set of local sources. 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 two sentences with high information density, front-loaded with the core function and lists key features and usage. Every sentence earns its place, and it remains concise despite covering many aspects.

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

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

Given the tool's complexity (multiple sources, baseline comparison, cascade computation), the description covers the purpose, the data sources, the key output (delta % and cascade), and usage context. An output schema exists for return values, so the description doesn't need detailed output specs. The description is fully self-contained for an AI 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 description covers 100% of the parameter, so baseline is 3. The description adds context about platform-specific source usage, but the description does not explain the parameter format or behavior beyond what the schema already provides.

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

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

The description clearly states the tool 'Pull token usage from ALL four local sources in parallel' and specifies the exact sources and computation of delta percentages and cascade metrics. It distinguishes itself from siblings like 'tokenpull' by emphasizing the comparative and validating nature.

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

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

It explicitly says 'Useful for validating your numbers before submitting, or understanding discrepancies between tools' and provides guidance on which platforms use which sources ('Claude only for token-dash; codex and others use tokenpull + ccusage + tokscale'). This is clear when-to-use context and differentiates from alternative tools.

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

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

Annotations already establish readOnlyHint and idempotentHint, but the description adds substantial behavior the annotations cannot convey: it is preview-only with no board publication, it reads the four canonical pillars per window from local logs, and it guarantees token-only access with no prompt content read or transmitted. This is exactly the extra context the dimension rewards.

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?

Content is front-loaded: the first sentence gives the verb, scope, and preview framing, followed by mechanism, the preview-only constraint, and the publishing alternatives. It is longer than strictly necessary (the endpoint/auth mechanics could be tightened), but every clause carries decision-relevant information.

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

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

With an output schema present, the description needn't explain return values, and it covers the gaps that matter: default platform, window semantics, privacy guarantees, and the correct publishing path. For a tool whose name implies submission but which only previews, this is complete enough 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?

Schema description coverage is 100% and each parameter (window, codename, platform) already carries a detailed enum list and semantics, including the 'multi' and 'devin' special cases. The description adds only the correct default (claude) and per-window framing, so the schema does the heavy lifting and a 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 states a specific verb and resource (pull LOCAL token usage from session logs, compute the cascade per window) and draws a hard line against the misleading tool name by declaring it PREVIEW-ONLY. It expressly distinguishes itself from submit_verified and the web UI, so an agent can tell it apart from siblings without opening schemas.

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

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

It states when to use this tool (local preview of cascade metrics) and when not to (publishing to the board), and names the two concrete alternatives: submit_verified and the signalaf.com web UI. The reason publishing is unavailable here (MCP tools don't carry an authenticated Supabase session) is given explicitly.

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 include readOnlyHint=true, so the description does not need to state that this is a read operation. The description adds context about the lumping behavior and the return format, but no additional behavioral traits beyond what annotations already provide.

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

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

The description is two sentences plus an example and return structure. It is concise, front-loaded, and every sentence adds value. No wasted words or redundancies.

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

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

The description covers the tool's purpose, parameter, example usage, and return format. It is adequate given the presence of annotations and output schema. A slight improvement could be mentioning that this is a read-only operation, but that is already covered by annotations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the threshold's effect (lumping models below threshold into 'other') and giving an example, which goes beyond the schema's description of 'fraction of their platform's total tokens'.

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 ('Show'), the resource ('per-model breakdown of your token usage'), and the scope ('across all platforms detected by tokscale'). It effectively distinguishes this tool from siblings by specifying the model-level breakdown, which is unique among the listed 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 explains when to use this tool: to see which models you actually use per platform. It provides guidance on the threshold parameter and its default behavior, but does not explicitly mention when not to use it or suggest alternatives.

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

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

The description discloses that all data is local (own usage, not aggregate) and explains fallback behavior (lists clients if target not found). ReadOnlyHint is already true, so no contradiction. Adds useful context about scope and data source.

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 informative paragraph with no wasted words. It could be slightly more structured (e.g., bullet points), but it is concise and front-loaded with purpose.

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

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

Given only one parameter, complete schema coverage, and an output schema (not shown but exists), the description covers all needed context: input format, return data details, fallback behavior, and data source. It is fully adequate for correct tool 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 single parameter 'target' is fully described: it accepts client slugs or canonical names, case-insensitive, and the description provides examples and suggests discovering valid slugs via another tool. This adds significant meaning beyond the schema 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 clearly states the tool provides competitive intelligence for any AI tool company, specifying that you pass a target tool and it returns rank, full profile, head-to-head comparisons, and market totals. It distinguishes from siblings by focusing on single-tool benchmarking against competitors using local usage data.

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

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

The description explains when to use (to benchmark one AI tool against competitors) and what happens if target not found (lists all detected clients). It suggests calling tokscale_market_share for valid slugs. However, it does not explicitly state when not to use or provide alternatives to other siblings.

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

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

Annotations declare readOnlyHint=true, so the read-only nature is covered. The description adds behavioral context by detailing the output structure (cost breakdown, rollups, totals) and the data source (local tokscale data). No contradictions.

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

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

The description is front-loaded with the core purpose and includes necessary details without excessive verbosity. Every sentence serves a purpose, though some minor redundancy exists.

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 the tool has no parameters and an output schema exists, the description sufficiently explains the return values and data source. It 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 tool has no parameters, and schema coverage is 100%. The description states 'No parameters' and explains that the cost breakdown is derived from tokscale models data, which adds minimal value beyond the schema.

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

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

The description clearly states the tool's function: cost analysis per developer per model from local tokscale data. It specifies the output structure (per-client × per-model breakdown with metrics) and explicitly distinguishes it from the sibling tool tokscale_market_share for market share analysis.

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

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

The description provides explicit when-to-use guidance ('Use this to see exactly where your AI spend goes') and when-not-to-use ('Do NOT use this for market share — use tokscale_market_share for that'), with a named alternative.

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

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

Annotations already declare readOnlyHint=true, so the description does not need to reiterate safety. The description adds valuable behavioral context: it returns a summary, all filesystem paths are redacted (home dir → ~), and includes headless support flag. No contradictions.

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

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

The description is dense with information but remains efficient; each sentence adds value. It is front-loaded with the main purpose and includes usage guidance. Minor improvement could be more structured bullet points, but overall it is concise.

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

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

Given no parameters and an existing output schema, the description covers all essential context: it describes the data returned, how paths are redacted, and provides a usage note. It is complete for the tool's purpose.

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

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

There are zero parameters, and schema description coverage is 100% (trivially). Description adds meaning beyond schema by elaborating on what the returned profile includes (model mix, token pillars, etc.), which is useful context.

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 provides a per-developer usage profile across all 20+ AI tools detected by tokscale, listing specific data points like model mix, token pillars, and summary fields. It distinguishes itself from sibling tool tokscale_cost_analysis by explicitly stating it is not for cost-only analysis.

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

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

The description explicitly says when to use this tool ('to understand your full AI tool footprint') and when not to ('Do NOT use this for cost-only analysis') while directing to the appropriate alternative (tokscale_cost_analysis). This provides clear usage guidance.

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

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

Annotations already indicate readOnlyHint=true. Description adds valuable behavioral context: paths are redacted to prevent local username leaks. 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?

Description is informative but slightly verbose; could be tightened. However, all sentences add value, and key info is front-loaded. Acceptable for a parameterless tool.

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 parameters and an output schema present, the description covers all relevant aspects: purpose, scope, data privacy, and local-only nature. No gaps.

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

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

No parameters (0 params, baseline 4). Description correctly notes 'No parameters. Profiles the local machine via tokscale.' The description adds no extra param semantics but is accurate.

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

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

Description clearly states it profiles the local machine's AI tool footprint, listing specific data points (installed tools, session logs, activity patterns). The 'local-only' distinction effectively differentiates it from siblings.

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

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

Provides explicit usage guidance: 'Use this to audit your own machine's AI tool installation and activity pattern.' Also clarifies context by stating 'This is local-only — it profiles the current machine, not remote devices,' which helps avoid misuse.

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 openWorldHint=false. Description adds context: 'All data is read locally from tokscale's scan of your session logs — no network calls, no PII.' This reinforces safety and discloses the data source beyond annotations.

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

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

Description is concise (~80 words) and front-loaded with purpose. Every sentence adds value: purpose, aggregation method, output format, data privacy, usage guidance, and negative guidance. No redundant information.

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

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

Given 0 parameters, rich annotations (readOnlyHint, openWorldHint), and presence of output schema, the description fully covers what the tool does, how it works, what it returns, and when to use it. 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?

No parameters; schema coverage is 100% with empty schema. Description is not required to add parameter details, and baseline for 0 params is 4. The description confirms lack of parameters by stating 'No parameters' in schema.

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

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

Description clearly states 'Complete AI tool market share analysis', specifying aggregation by client and computation of shares for tokens, cost, messages. It distinguishes from sibling tool 'tokscale_developer_profile' by directing users elsewhere for per-model detail.

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

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

Explicit usage guidance: 'Use this to see which AI coding tools dominate your workflow' and 'Do NOT use this for per-model detail — use tokscale_developer_profile for that.' Also notes data is local with no network calls or PII.

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 behavioral context: data source (local tokscale), detection window, and handling of no servers detected. 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 concise with no unnecessary words. It is front-loaded with the purpose and structured logically, covering key points in a few sentences.

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

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

For a no-parameter tool, the description is complete: it explains the data source, report contents, and behavior when no servers are detected. No gaps given the 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?

No parameters exist, and schema description coverage is 100%. The description adds meaning by explaining the report contents (detection window, active days) and the case of no detection.

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 reports MCP server usage patterns, including detected servers, detection window, and active days. It distinguishes itself from sibling tools by focusing on local tokscale MCP server detection.

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

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

The description explicitly states when to use (to see which MCP servers are active) and hints at the absence of results scenario. However, it does not explicitly mention when not to use or directly compare to siblings, which have different purposes.

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 behavioral context beyond the readOnlyHint annotation, detailing data sources (monthly aggregates + per-day contribution) and output structure (first_seen, last_seen, active_days, tokens, clients, adoption_curve). 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, front-loading the main purpose, then providing details. Every sentence adds value, though it could be slightly more concise. However, it remains clear and informative.

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

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

Given the tool has no parameters and an output schema exists, the description adequately explains the output structure (months[], models[], adoption_curve[]) and the data fields. Could mention scope (all time?) but sufficient for a read-only reporting 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?

No parameters, so baseline 4 applies. The description explicitly states 'No parameters. Derives trends from tokscale monthly + graph data,' which is clear and sufficient.

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

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

The description clearly states the tool tracks 'Model adoption trends over time' from tokscale data, specifying the output includes monthly aggregates, per-day data, and model-level timeline fields. It also distinguishes from sibling tool tokscale_cost_analysis by explicitly stating not to use for cost trends.

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

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

Provides explicit guidance on when to use (track model adoption and evolution) and when not to use (for cost trends, use tokscale_cost_analysis). This is a clear directive for the agent.

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 (idempotentHint: true, openWorldHint: false), the description discloses important behaviors: calls never block or loop, interval_s is advisory, and the submit path is rate-limited to once per 5 minutes per platform+window and requires enrollment. This adds substantial context that is not present in 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 two sentences, front-loaded with the key behavioral point ('One poll per call'), and every clause carries useful information. There is no redundancy or filler; it is concise yet comprehensive.

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 multiple optional parameters, an output schema, and an optional submit path, the description fully covers the operational model, rate limits, prerequisites, defaults, and the non-blocking nature. No significant gaps remain for an agent to select and invoke the tool correctly.

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

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

The input schema already has 100% description coverage, but the tool description enriches it further: submit requires enroll and is rate-limited, interval_s is advisory and echoed back as poll_interval_s, and the default behavior is preview-only. This goes well beyond the schema descriptions, making the parameters' practical semantics clear.

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

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

The description clearly states what the tool does: 'One poll per call: pulls your local token logs and returns the current cascade for the watched window.' It uses a specific verb (pulls) and resource (local token logs), and distinguishes itself from sibling tools by emphasizing it never blocks or loops and by explaining preview-only vs submit modes.

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

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

The description gives explicit usage guidance: 'Re-call at your desired cadence to watch for changes' and notes that interval_s is advisory only and echoed back as poll_interval_s. It also explains when to use submit:true (with an enrolled device) and when to stick with preview-only (default), effectively covering when and when-not 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.