SigRank — AI Operator Benchmarking

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed world), so the description is free to add operational context — and it does, listing the concrete comparison outputs (percentile, rank, distance from median, distance from top 10%, strongest/weakest metric, interpretation). It also discloses the two input modes (4 pillars vs codename), adding value where there is no output schema.

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

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

Front-loads the core question and purpose in the first clause, then enumerates outputs and usage. It is longer than minimal, but each sentence carries information (inputs, outputs, routing framing) rather than padding.

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

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

For a 9-parameter tool with no output schema, the description adequately explains both input modes and enumerates the returned comparison metrics, and the annotations cover the safety profile. Gaps are minor — no mention of behavioral nuance such as how the time window affects results or what happens when a codename is not found.

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 every parameter and the baseline is 3. The description adds modest value by grouping input/output/cache_read/cache_write as '4 token pillars' and noting codename as the alternative, but it introduces no syntax or constraint detail beyond the schema.

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

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

States a specific verb and resource ('benchmarks your token cascade against the live field') and frames itself with a distinctive human-question angle ('This is the human-question tool'). It does not name a specific sibling to route against, but the 'am I a power user / how do I compare' framing is enough to separate it from get_leaderboard and compare_to_field.

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 concrete trigger conditions with quoted user phrasings ('am I a power user?', 'how do I compare?'), which is clear when-to-use guidance. It stops short of naming alternatives or stating when NOT to use it, so it does not reach the explicit when/when-not/alternative bar of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds that it fetches a live leaderboard (external dependency) and returns percentile-bucketed metrics, which is useful beyond the annotations, but it omits caching/pagination or failure behavior.

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

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

The first sentence is well front-loaded and states the output format, but the trailing 'Simple, useful, and immediately understandable' sentence adds nothing and dilutes an otherwise tight description.

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 return metrics are described (yield, leverage, velocity, SNR across quartile/decile/percentile buckets), which is good since no output schema exists. However, with 9 params at 44% coverage and an unexplained 'pillars' concept, an agent lacks enough 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 44% across 9 parameters, so the description must compensate. It mentions 'codename' but not the input/output/window/cache_read/cache_write params, and references '4 pillars' which does not map to any obvious schema field, creating ambiguity rather than clarity.

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 concrete verb+resource: creates a comparison table for cascade metrics with a named set of benchmarks (field median, top 10%, top 1%). It differentiates itself from get_leaderboard by describing the output shape, though it doesn't explicitly name which sibling it competes with.

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

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

No when-to-use guidance and no contrast with siblings like benchmark_me, get_leaderboard, or rank_if, which all plausibly overlap. The closing 'Simple, useful, and immediately understandable' is marketing, not routing 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 readOnly/idempotent/non-destructive, so the safety bar is met. The description goes further by disclosing the returned artifact (ranked leaks with severity levels, findings, recommendations, and estimated Υ impact) and the six checks performed, which is real behavioral value beyond the annotations.

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

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

Front-loaded with purpose, then output, then the check list, then usage guidance. Three sentences with no filler, though the enumerated check list is dense and slightly list-like rather than prose.

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

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

No output schema exists, so the description correctly carries the return-value burden (ranked leaks, severity, findings, recommendations, Υ impact). Combined with annotations covering safety, an agent has what it needs; only edge details like pagination or input validation limits are 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?

Schema coverage is 100%, so each parameter is already documented and baseline is 3. The description adds a conceptual grouping — "4 token pillars" — that maps to the core numeric inputs and signals they are the primary drivers of the analysis, slightly 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?

States specific verbs (analyzes, diagnoses) and resources (token cascade, efficiency leaks) and describes the concrete output (a ranked leak list with severity). It also names the sibling simulate_change, so an agent can place it relative to the rest of the suite 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?

"Use this before simulate_change to understand what's wrong" gives an explicit ordering/context and names the alternative. It stops short of stating when NOT to use it or the full diagnostic-vs-simulation boundary, so it's clear context rather than complete routing.

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 (readOnly, idempotent, non-destructive, closed-world). The description adds one genuine behavioral trait beyond them: this tool is meant to fire without user prompting. It says nothing about rate limits, cost, or refresh cadence, so it is minimum-viable rather than 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?

A single front-loaded sentence states the purpose, followed by a compact 'Returns:' list that front-loads the outcome. Dense but every clause earns its place; only mild bloat from the marketing line at the end.

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

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

With no output schema, the description usefully enumerates the returned anomaly types, which is exactly what the agent needs. It omits any explanation of the window parameter's effect, a minor gap given the otherwise adequate coverage.

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 75%, so most parameters (context, llm_model, conversation_id) are self-documented in the schema. The description contributes nothing about the 'window' enum or how parameters shape the anomaly set, so it sits at the baseline for a well-covered schema.

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

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

States a specific verb ('Finds') and resource (unusual operators, metric relationships, outliers in the live leaderboard), and enumerates the concrete anomaly categories returned. This distinguishes it from siblings like get_leaderboard and operator_gap, though the enumeration is loose and the exact computation is not pinned down.

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?

'Without user prompting' implies a proactive/autonomous trigger, which is the only usage cue. There is no explicit when-to-use versus siblings such as get_leaderboard or operator_gap, and no exclusions or preconditions are stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the useful fact that results are public and enumerates returned columns, but says nothing about pagination, ordering/determinism, or freshness/caching of the leaderboard.

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

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

Two tight sentences: what it reads, then what it returns. Nothing is wasted and the purpose is front-loaded.

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

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

With an output schema present, return values need not be spelled out, and the description still names the key fields. Parameters are fully documented in the schema, so the only real gap is the absence of any routing guidance against the many sibling ranking tools.

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

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

Schema description coverage is 100% and every parameter (limit, window, context, llm_model, conversation_id) carries its own inline documentation with ranges, enum values, and defaults. The description adds no parameter-level meaning, so the schema-driven baseline of 3 applies.

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

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

The description states a specific verb and resource ('Read the current public SigRank operator leaderboard') and even enumerates the returned fields. It is clearly distinguishable from lookups like get_operator, but it never names or contrasts with sibling ranking tools such as rank_windows or rank_if.

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 guidance: no mention of when a public global leaderboard is preferable to rank_windows, rank_if, or compare_to_field, and no stated prerequisites or exclusions. Usage is only implied by the word 'leaderboard'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds the returned metric set but says nothing about failure modes (e.g., unknown codename), which is the main behavioral gap remaining.

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

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

Two short sentences, front-loaded with the action and the returned fields, with zero filler or repetition.

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

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

For a simple single-record read with a rich output schema, the description is essentially sufficient; the return values need not be explained since an output schema exists. The only missing element is what happens when the codename does not resolve.

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 codename, context, llm_model, and conversation_id are each fully documented in the schema itself. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource ('Read one public operator profile by codename') and enumerates the returned metrics, so the agent knows exactly what it retrieves. It does not explicitly contrast itself with close siblings like operator_signature or get_sigrank_standard_record, keeping it 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?

There is no explicit when-to-use guidance, no prerequisites, and no named alternatives among the many sibling tools. The 'by codename' phrasing only weakly implies the usage context (you already hold a codename), leaving the agent to infer when this beats get_leaderboard or operator_signature.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description nonetheless adds valuable behavior: 'unavailable cache telemetry remains null,' 'does not submit or persist data,' and 'Computes only the five-metric portable core through token-cascade' — facts not in annotations.

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

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

Three front-loaded sentences, no filler. The key scope constraint (input/output required, cache nullable) and the non-persisting nature are stated upfront. Every sentence carries weight.

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. The description covers computation model, null handling, and non-persistence. An agent can call this correctly. Minor gap: no mention of the draft/versioning implications or error behavior, but not critical.

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 per the rubric the baseline is 3 even if the description adds no parameter-level detail. It does briefly note that input/output are required and cache fields may be null, but the schema already documents all of this thoroughly.

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 artifact: 'Build a tteop/0.1-draft portable operator record from available token telemetry.' The agent knows it produces a structured record from telemetry, distinguishing it from siblings like diagnose_cascade or get_leaderboard.

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

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

The description implies data must be available and that this is a computation-only step, but it doesn't state when to choose this tool over siblings like operator_signature or get_operator, nor any exclusions. Usage is inferable but not explicit.

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

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

Annotations already establish readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description usefully adds that both cascades are computed and a single most-explanatory factor is returned, but says nothing about determinism guarantees, cost, or handling of partial inputs.

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?

Led by the core question and then progressively elaborates cause hierarchy and the decomposition, so it is front-loaded and dense. Slightly long with em-dash clauses, but every clause adds distinct information.

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

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

For a 13-parameter, no-output-schema analytics tool, the description covers the conceptual input modes and the returned factor but leaves the codename-vs-pillar precedence, required context/llm_model plumbing, and conversation_id sequencing to the schema. Adequate but with clear 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 only 38% across 13 parameters, so the description must carry weight. It explains the two input modes ('two codenames or two sets of pillars'), which covers a_codename/b_codename and the a_*/b_* pillar params at a high level, but adds no meaning for context, llm_model, conversation_id, or the distinction between read/write/input/output pillars.

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 question it answers ('What specifically separates operator A from operator B?') and enumerates the decomposition (leverage, velocity, SNR, scale) plus the output (the most explanatory factor). This clearly distinguishes it from siblings like compare_to_field or get_operator, which don't decompose a gap.

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

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

The description implies when to call it by framing the comparison question, and notes it accepts 'two codenames or two sets of pillars'. However it never names alternatives (e.g., compare_to_field or who_operates_like_me) or states when NOT to use it, leaving routing 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 declare this a safe, idempotent, closed-world read. The description adds genuine behavioral context beyond them: the returned fields, the fact that 'archetype' is deprecated but retained as a compatibility alias, and that the labels are NOT the 10-type Build Archetypes reference extension — a useful disambiguation against a likely-confused reference set.

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 tight clauses, front-loaded with the core verb and resource, then return values, then the deprecation caveat. No filler sentences; slightly dense jargon but every clause carries 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 9 parameters, 44% schema coverage and no output schema, the description usefully enumerates return fields and flags the deprecated alias. It still omits which inputs are required (context and llm_model) and how the pillars map to parameters, so it is adequate but not complete for a tool of this complexity.

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

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

Schema coverage is only 44%, so the description must compensate, and it partially does by framing the input as '4 token pillars or a codename.' But it never identifies which parameters are the pillars (input/output/cache_read/cache_write) or explains window's enum, leaving several undocumented parameters unresolved.

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: 'Computes a normalized operating signature from 4 token pillars or a codename,' and lists the outputs. However, it never distinguishes itself from close siblings like get_operator or who_operates_like_me, which plausibly return overlapping identity/comparable data, so an agent must infer the boundary.

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

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

The description implies usage by noting two input modes (pillars vs. codename) but gives no when-to-use/when-not guidance and names no alternative tool. With 16 sibling tools including several identity-shaped ones, the absence of routing guidance is a real gap.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real value beyond them by disclosing the return payload — current rank/percentile, simulated rank/percentile, required pillar changes, and yield delta. It does not mention the stateful conversation_id handshake, but that is documented in 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?

Front-loads the question the tool answers, then states inputs, outputs, and usage in a tight sequence. The closing line 'This turns SigRank from a scoreboard into a simulator' is mild marketing fluff rather than essential information.

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

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

For a 9-parameter, 7-required tool with no output schema, the description supplies the purpose, inputs, return values, and a usage trigger. Annotations cover safety. Only the server-side conversation_id sequencing is unaddressed here, and that lives in the schema.

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

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

Schema description coverage is 100%, so all nine parameters are already documented. The description adds conceptual grouping ('your current 4 token pillars') and restates the percentile meaning, but no format or syntax beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb and resource — it simulates the metric changes needed to hit a target rank percentile using the four token pillars — and enumerates its outputs. It is clearly distinguishable from read-only siblings like get_leaderboard, though it never explicitly contrasts itself with the overlapping simulate_change or suggest_improvements.

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 trigger ('use it when someone asks "what would move my rank?" or "how do I get to top 10%?"') plus a concrete percentile example. It stops short of naming alternatives or stating when NOT to use it versus sibling simulators.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so the safety profile is covered. The description usefully adds 'No data is persisted' and 'without submitting data', which are behavioral claims persistence annotations do not express. However it does not cover errors, edge cases, or computation assumptions.

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 short sentences, front-loaded with the action and input, then the returns, then the persistence guarantee. No waste; each sentence carries distinct 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?

An output schema exists, so the description need not enumerate return values, yet it does as a bonus. With full schema coverage and annotations covering safety, the only real gap is usage/routing context against the many SigRank siblings.

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 every parameter (including the required context and llm_model strings and conversation_id) is fully documented in the schema. The description's 'four non-negative token counts' loosely maps to input/output/cache_read/cache_write but adds no format or syntax detail. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb (Calculate) and resource (SigRank cascade metrics) and names the input shape (four non-negative token counts). It also lists the output metrics, so an agent knows what comes back. It does not explicitly distinguish itself from sibling analytics tools like diagnose_cascade or rank_if, which keeps it out of the top tier.

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

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

The phrase 'without submitting data' and 'No data is persisted' hints at a local/offline calculation mode, but the description never says when to pick this over alternative SigRank tools or what prerequisites exist. No when-to-use, when-not-to-use, or routing guidance is present.

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

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

Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, so the bar is low. The description still adds meaningful side-effect context by clarifying that results are computed independently per window and are 'NOT' submitted to the board, which is not derivable from the annotations.

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

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

Three tight sentences, front-loaded with the action and window set, followed by the scoring detail and the critical boundary. No filler; every clause carries information an agent needs.

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 7-parameter tool with nested objects and no output schema, the description covers the core mechanics: what is scored, the cascade components (Υ, SNR, Leverage, Velocity, 10xDEV, class), and the non-submission guarantee. It does not describe the return shape or ordering of per-window results, which is the main residual gap given no output schema exists.

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

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

Schema description coverage is 100%, so the baseline is 3, and the schema already documents each window object and the context/llm_model/conversation_id fields. The description adds a genuine constraint not enforced by the schema — that 1-4 windows may be supplied and windows may be omitted — improving correct invocation.

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 ('Score up to 4 time windows') and defines scope via the batch capability and the boundary 'Does NOT submit to the board'. It never names a sibling (rank_if, rank_paste), so sibling differentiation is inferred rather than explicit.

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

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

Gives real guidance about partial input ('Omit windows you don't have — partial input is allowed (1-4 windows)'), which is useful for calling correctly. However, it never says when to choose this over rank_if, rank_paste, or benchmark_me, leaving tool selection 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the pipeline behavior (five ordered steps) and what the call returns (diagnosis + suggestions + simulated impact). It stops short of noting cost, latency, or whether the four token pillars must all be non-zero.

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 verb and structured as a numbered pipeline, which is easy to scan. The enumeration is mildly verbose, but each step conveys distinct behavior; the closing sentence adds usage timing rather than padding.

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

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

With no output schema, the description capably explains the return value ('complete cycle: diagnosis + suggestions + simulated impact'). Annotations cover safety and the schema covers all params. The remaining gap is the missing relationship to sibling tools, which matters for a composite that overlaps with other available tools.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters, making 3 the baseline. The description loosely maps '4 token pillars' onto the input/output/cache_read/cache_write tokens, but adds no syntax, units, or edge-case guidance for conversation_id, llm_model, or context beyond what the schema provides.

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

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

The description states a specific verb and resource ('Runs the full self-improvement cycle in one call') and enumerates the five concrete steps it orchestrates. The label 'one-click optimize tool' implicitly distinguishes it from the single-step siblings (diagnose_cascade, suggest_improvements, simulate_change) by framing it as the composite that does all of them.

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

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

It gives clear context for use: 'call it at the end of a session to see what to improve next time.' That is a strong when-to-use signal. However, it never names or contrasts with the sibling tools that perform the individual steps, so an agent weighing the composite against chaining diagnose_cascade + simulate_change gets no explicit routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-mutating simulation. The description adds useful context about the dual-run comparison (current vs proposed) and the relative/absolute value semantics, but does not discuss auth, rate limits, or the conversation_id lifecycle.

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

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

Three sentences, front-loaded with the tool's identity and value proposition, then the output, then the value-format rule. No filler and nothing repeated.

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 required-heavy (7 required params) simulation tool with nested objects, the description conveys what the tool returns and how changes are encoded. It does not clarify how cache_read/cache_write pillars are treated or whether the conversation_id lifecycle affects parallel calls, but the schema covers those parameters, so the gap is minor.

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

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

Schema coverage is 100%, so all 8 parameters are already documented in the schema, including the changes object with its +/- relative delta semantics. The description restates the absolute-vs-relative convention but adds no syntax, format, or constraint detail beyond the schema, 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+resource ('simulate change', 'what-if cascade predictor') and the exact output it produces (Υ Yield delta, class change, per-metric diffs). It is clearly distinguishable from siblings like diagnose_cascade (diagnosis vs simulation) and rank_if (ranking vs what-if).

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 clear when-to-use frame ('test proposed pillar changes and see the payoff before changing your workflow'), implying the pre-commitment scenario. It does not explicitly name an alternative sibling (e.g., diagnose_cascade) or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so safety is covered. The description adds that it tests multiple strategies and returns a ranked list plus best_single_change, but omits that the context parameter is analytics-only and that conversation_id is server-issued and must be reused. It also doesn't contradict the annotations.

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

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

Three tight sentences that front-load the purpose, then the strategy, then the output fields. No filler, though listing every returned field is slightly list-like where a single phrase could suffice.

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

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

No output schema exists, so the description correctly enumerates the return shape (action, pillar, projected Υ, yield delta, projected class, rationale, best_single_change). Combined with annotations covering the safety profile, an agent has enough to invoke and interpret the call, though the special conversation_id reuse contract is only in the schema.

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

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

Schema coverage is 100%, so the schema documents all seven params including the special context analytics constraint and conversation_id rules. The description names the four token pillars it operates on, reinforcing which inputs matter, but adds little beyond the schema's own parameter descriptions.

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

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

Specific verb (generates) + resource (ranked, simulated improvement suggestions for a token cascade) with the mechanism and output named. Clearly distinguishable from siblings like simulate_change and diagnose_cascade because it states it ranks suggestions by Υ yield impact.

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?

Implied use case (optimizing a token cascade) but no explicit when-to-use vs the similar simulate_change, which sounds like it simulates a single change while this simulates and ranks multiple. No exclusions or routing guidance are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so safety is covered. The description adds real behavioral context beyond that: it computes your signature, queries the live leaderboard, and enumerates the returned comparison dimensions (similarity %, outperform directions, differentiators).

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 core purpose and the computation flow, and the return-value list is informative. The closing sentence, 'Makes the leaderboard feel like a network, not a list,' is marketing fluff that does not earn its place.

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

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

No output schema exists, so the description correctly carries the return-value burden and does so reasonably well. However, for a 10-parameter tool with 50% schema coverage, the parameter surface (pillars, limit, window) is left under-explained, leaving gaps an agent must resolve from the schema alone.

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

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

With 10 parameters and only 50% schema description coverage, the description must compensate. It mentions '4 pillars or a codename' but never names the four pillar parameters (input/output/cache_read/cache_write), and says nothing about limit, window, or the analytics-only context/llm_model params. It adds marginal meaning only.

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: it finds operators whose operating signature resembles yours, via 4 pillars or a codename, using signature distance on the live leaderboard. This is clearly distinct from siblings like get_leaderboard or compare_to_field, though no sibling is named explicitly.

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

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

The description implies the usage context (find operators similar to you) and names the two input modes (4 pillars or codename), but gives no explicit when-to-use guidance, no exclusions, and no routing to alternatives such as compare_to_field or operator_gap.

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