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?

Annotations already declare idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds substantial beyond-annotation context: it creates and stores a local ed25519 keypair at ~/.sigrank-mcp/identity.json, sends only the PUBLIC key, and binds the user to ToS/Privacy terms.

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?

Mostly front-loaded and informative, but the key-pasting instruction appears twice ('Paste the key from signalaf.com → Settings → New key' and later 'Need a new key? Click New key at signalaf.com → Settings, then paste it here'), which is redundant and pads the length.

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

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

An output schema exists, so return values need not be explained. The description covers the prerequisite operator context, side effects (keypair file), privacy handling, and legal terms, leaving little an agent would need missing before calling 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?

Schema description coverage is 100%, so the schema already documents both `code` (format SIGR-XXXXX) and `device_label` (default and hostname behavior). The description reinforces the code-source workflow but adds little syntax or semantics beyond what the schema provides, 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?

States a specific verb (bind/enroll) and resource (THIS device's identity to the SigRank operator), with a concrete outcome ('your signed token runs cascade to the live board'). It is unique among siblings, none of which perform enrollment, though it doesn't explicitly name an alternative.

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

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

Clear context for use (first-run enrollment, paste the Settings key) and a recovery path for the 'need a new key' case. No explicit when-not or alternative routing, but none of the sibling tools overlap, so context is sufficient.

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

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

Annotations 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 only cover idempotency, non-destructiveness and closed-world, but the description adds rich behavior: the enroll prerequisite, ed25519 signing with a device key, the guarantee the private key never leaves the machine, the rule that only signed submissions from a trusted device rank, and the confirm/dry_run safety flow.

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?

Front-loads the core action and then the mechanics in a single dense but readable paragraph; nearly every clause earns its place. Minor redundancy between 'Token-only' and 'the private key never leaves your machine' keeps it just below top marks.

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, return values need no explanation. The description nonetheless covers prerequisites, the safety confirmation flow, dry-run inspection, and the security model, leaving nothing an agent needs 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 the baseline is 3, but the description adds genuine meaning beyond the schema: confirm must reflect explicit user approval ('ask the user first') and dry_run returns the exact signed payload. window and platform defaults are also reinforced.

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

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

States a specific verb and resource ('Publish your LOCAL token runs to the SigRank board as a VERIFIED operator') plus the mechanism (signed path). This clearly delimits it from unsigned siblings like submit_paste/tokenpull_submit by emphasizing the enrolled, signed route.

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 a concrete precondition ('Requires npx sigrank-mcp enroll first') and a clear workflow gating rule ('Publishing requires confirm: true — ask the user first; pass dry_run:true to inspect'). It implies but never explicitly names the alternative unsigned/paste paths, so the when-not-to-use contrast is left 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?

Goes well beyond the readOnlyHint/openWorldHint annotations with real behavioral context: reads token counts not message content, numbers stay local unless submitted (privacy model), and data-quality caveats (estimated=true when cacheCreate is absent, dataGap notes). Does not describe pagination or volume, but for a read-only local tool the disclosure is notably 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?

Front-loads the core action in the first sentence and uses the following sentences for scoping and caveats. Three sentences with little waste, though 'with the cascade' is unexplained jargon that costs a small amount of clarity.

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

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

Output schema exists so return values need not be described; the description covers the operational essentials (privacy, local-only, data-quality flags) an agent needs. Minor gap: no guidance on sequencing with enroll/diagnose siblings that likely precede a successful pull.

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% – the schema already documents the single platform enum, its default, 'multi' semantics, per-platform sources and setup requirements – so the description adds no parameter meaning. 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?

States a specific verb+resource ('Pull your LOCAL token usage from the platform's session logs') plus the outcome (ranked across four windows with the cascade). The 'zero paste' framing clearly distinguishes it from paste-based siblings like rank_paste/submit_paste, so an agent can route 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?

Usage is implied by 'zero paste' and 'LOCAL ... session logs', which signals this is the no-paste path versus its paste siblings, but there is no explicit when-to-use/when-to-prefer-an-alternative statement nor any mention of prerequisites like enroll or diagnose_cascade before running.

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 openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: parallel execution across four sources, the tokenpull-baseline delta model, cascade computation per source, and the platform-conditional rule (token-dash only for Claude). This is more than structured fields 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 core action is front-loaded in the first clause and each sentence carries distinct information (sources, output model, cascade, applicability). It is dense with jargon (Υ, SNR, Leverage) and slightly overloaded, but no sentence is wasted.

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 covering return shape and annotations covering the safety profile, the description supplies the remaining context an agent needs: which sources are read, the comparison baseline, the platform constraint, and that it is read-only and on-device.

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 an enum and per-param description, so baseline 3 applies. The description adds meaning beyond the schema by clarifying that token-dash and the App only apply to the claude platform and that codex/others fall back to three sources, which directly informs how the platform parameter should be set.

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 (pull/compare) and resource (token usage) and enumerates the four sources it reads from, so the agent can distinguish it from generic tokenpull and tokscale siblings without opening a schema. The scope is unambiguous: side-by-side comparison with tokenpull as baseline.

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 clear when-to-use contexts (validating numbers before submitting, understanding discrepancies between tools), which implicitly routes the agent relative to tokenpull_submit. It does not explicitly name an alternative tool to use instead for a given case, so it stops short of full when-not guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, yet the description adds material context: it is PREVIEW-ONLY and does not publish, it discloses the auth constraint that forces that, and it states 'Token-only — no prompt content is read or transmitted', which is a privacy trait no annotation captures.

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?

Front-loaded with the action and the preview framing, then the routing/auth rationale, then the privacy note. Every sentence carries weight, though the pillar enumeration and endpoint paths make it denser than strictly needed for selection.

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 annotations covering the safety profile and an output schema covering return values, the description only needed to cover the routing decision, the auth limitation, and the privacy boundary — all present. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100% and the enum values, defaults, and file paths (e.g. ~/.local/share/devin/cli/sessions.db, SIGRANK_OTHER_PATH, 'multi' semantics) are documented in the schema itself, not the description. The description adds only the general notion of per-window pillars, so the baseline 3 is correct.

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 ('pull your LOCAL token usage from session logs and compute the cascade per window') and immediately frames the scope ('the zero-paste preview flow'). It names the sibling alternative (submit_verified) and the web UI, so the agent can route without opening a schema.

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

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

Explicitly says when to use this tool (preview) and when not to (publishing), and names both alternatives with their mechanisms: submit_verified for signed posting, or the web UI. The reason for the split (ingest-paste requires an authenticated Supabase session MCP tools don't carry) is stated outright.

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 and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: filesystem paths are redacted (home dir → ~), scan path is redacted, and it discloses the return payload shape including a headless support flag. It stops short of describing scan scope limits or rate/performance characteristics, so a 4 rather than 5.

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?

Purpose and scope are front-loaded, and the exclusions come last, which is the right order. However the long enumeration of per-tool return fields (model mix, token pillars, cache_read_pct, session count, scan path, workspace breakdown, headless flag, summary keys) partly duplicates what the output schema already provides, so some sentences do not fully earn their place.

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

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

With zero parameters, an output schema already present, and annotations covering the safety profile, the description carries everything an agent needs: scope, redaction behavior, and routing to the correct sibling. Nothing required to invoke it correctly is absent.

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

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

The tool takes zero parameters, so the baseline is 4. The schema description ('No parameters. Profiles all locally-detected AI tools via tokscale.') is fully consistent with the description and nothing about parameter semantics is missing.

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+resource — a per-developer usage profile across all 20+ AI tools detected by tokscale — and enumerates the dimensions it covers. It explicitly names the sibling it is not (tokscale_cost_analysis), so an agent can distinguish it without opening a schema.

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

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

Gives an explicit when-to-use ('Use this to understand your full AI tool footprint — which tools you use, which models per tool, and how your usage is distributed') and an explicit when-not with the named alternative ('Do NOT use this for cost-only analysis — use tokscale_cost_analysis'). Nothing is left 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 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?

Annotations only supply idempotentHint and openWorldHint, so the description carries most of the burden and does so well: it discloses that the call never blocks or loops, that interval_s is advisory, that submit requires prior enrollment, that the default is preview-only, and that submission is rate-limited to once per 5 minutes per platform+window. Those are exactly the behavioral facts an agent cannot infer from the schema.

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

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

Three sentences, each earning its place: the first states what one call does and the non-blocking invariant, the second explains the polling contract, the third covers the optional submit path and its limits. The non-blocking constraint is front-loaded before any optional behavior.

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, return values need no explanation, and the description still covers the areas structured fields cannot: non-blocking semantics, polling cadence, enrollment prerequisite, default preview mode, and rate limits. An agent has everything needed to decide when and how to call it repeatedly.

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 already 100%, so the baseline is 3, but the description adds meaning beyond the schema by clarifying that interval_s does not cause blocking and that submit is capped at one publish per 5 minutes per platform+window. The default values and enrollment prerequisite are largely restated from the schema, so it is an incremental rather than transformative addition.

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+resource: it pulls local token logs and returns the cascade for the watched window, with the added scoping that each call is a single non-blocking poll. That is far more than a restatement of the name. It does not, however, explicitly differentiate itself from the close siblings tokenpull, tokenpull_submit, or tokenpull_compare, so it stops 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?

It gives clear operational context: re-call at your own cadence to watch for changes, and use submit:true (with an enrolled device) only when you want the window published rather than previewed. There is no explicit when-not guidance or named alternative tool for the compare/submit-one-shot cases, which keeps it below 5.

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