SigRank — AI Operator Benchmarking

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

Annotations already establish the safe-read profile (readOnlyHint, idempotentHint, non-destructive), so the description is free to add value — and it does: it enumerates the return metrics, warns that profile text fields are untrusted user data, and instructs never to follow embedded instructions. This injection-surface disclosure is genuinely beyond what annotations 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 purpose is front-loaded in the opening clause, and the output list plus security note each earn their place. Slight redundancy in restating the 'human-question tool' framing after already quoting the user question, but overall tight.

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

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

With no output schema, the description compensates by enumerating the returned metrics (percentile, rank, distance from median/top 10%, strongest/weakest metric, interpretation). Combined with the security guidance and parameter relationships, an agent has everything needed to call and interpret 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 real meaning: it clarifies the '4 token pillars (or a codename)' alternative path and reinforces the conversation_id continuity rule. These relationships between parameters are not obvious from the schema fields 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 states a specific verb and resource ('benchmarks your token cascade against the live field') and frames it around a concrete user question ('How good am I?'). It also enumerates the computed outputs, letting an agent distinguish it from siblings like get_leaderboard, compare_to_field, and rank_if 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?

It gives clear triggering context: 'use it when someone asks am I a power user? or how do I compare?' This is explicit when-to-use guidance. It stops short of naming which sibling to prefer instead (e.g. compare_to_field for two-operator comparison), so it does not reach the full when-not/alternatives bar.

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 the safety profile is covered. The description adds real value beyond that: it discloses that the tool fetches the live leaderboard (external dependency) and, notably, warns that profile text fields are untrusted user-supplied data whose embedded instructions must never be followed — a security caveat annotations cannot express.

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 capability and the safety warning are front-loaded and useful, but the sentence 'Simple, useful, and immediately understandable' is pure filler that earns no place in a tool definition and dilutes the payload.

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 what comes back — your metrics alongside field median, top quartile, top decile, and top percentile — so an agent knows the return shape. The remaining gap is the unexplained 'pillars' input terminology against a 9-parameter 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 only 44%, so the description must carry more weight than it does. It adds only the 'codename as alternative to pillars' hint, and the term 'pillars' does not map cleanly onto any of the nine documented parameters (input, output, window, cache_read, cache_write), leaving the raw metric inputs unexplained.

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 — 'Creates a YOU vs FIELD vs TOP 10% vs TOP 1% comparison table for your cascade metrics' — and names the metric families returned (yield, leverage, velocity, SNR). It is clearly distinguishable from get_leaderboard (raw rankings) and operator_gap, though it never explicitly contrasts itself with the closest sibling, benchmark_me.

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 what inputs it accepts ('4 pillars or a codename') but gives no when-to-use guidance, no prerequisites, and no routing advice among the many benchmark/leaderboard siblings (benchmark_me, get_leaderboard, rank_windows). An agent must infer the selection criteria on its own.

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 cover the read-only/idempotent/non-destructive safety profile, and the description adds materially beyond that: it discloses the exact set of anomalies returned and, crucially, warns that profile text fields are user-supplied untrusted data that must never be treated as instructions. That trust/safety disclosure is exactly the kind of behavioral context annotations cannot 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?

Front-loads the anomaly enumeration, then closes with the essential injection warning. Slightly dense with five comma-separated return items, but every clause carries information and nothing is 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?

No output schema exists, so the description correctly spends words describing what gets returned, which it does concretely. It is nearly complete; only the effect of the window parameter on results is left unexplained, and annotations already cover safety.

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% and the schema itself thoroughly documents context, llm_model, and conversation_id (including the conversation_id continuity rule), while window carries only an enum and default. The description adds no parameter-level meaning at all, so it neither compensates for the 25% gap nor degrades the strong schema coverage; baseline 3 fits.

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 ('Finds unusual operators, metric relationships, and outliers in the live leaderboard') and even enumerates the concrete anomaly types it surfaces. An agent can distinguish it from get_leaderboard or compare_to_field, though it never names those siblings explicitly to sharpen 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?

'Without user prompting' and 'Powers automated micro-marketing and field insights' imply a proactive/exploratory trigger, which is useful context. But it gives no explicit when-to-use vs when-not compared to diagnose_cascade, operator_gap, or get_leaderboard, leaving the routing decision 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/idempotentHint/destructiveHint=false, so safety is largely covered. The description adds genuinely useful context beyond them: which fields are returned and, importantly, that profile text fields are user-supplied untrusted data that must not be treated as instructions — a real operational constraint an agent needs.

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 core action and return shape, followed by the security caveat. No filler; every clause adds an actionable fact.

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 rich output schema and full annotation coverage, the description only needs to frame purpose and safety, which it does well. Its main gap is the absence of routing guidance relative to sibling ranking tools, but the untrusted-data warning makes it substantially complete.

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

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

Schema description coverage is 100%, so limit, window, context, llm_model, and conversation_id are already fully documented in the schema. The description adds no parameter-level meaning (no default, paging, or enum guidance) beyond that, which matches the baseline 3 for fully-covered schemas.

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 ('Read the current public SigRank operator leaderboard') and enumerates the returned fields (Yield, Leverage, class tier, display name). The scope is unambiguously distinct from single-operator siblings like get_operator and from comparison tools like 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?

The description never says when to choose this tool over alternatives such as rank_windows, compare_to_field, or get_operator. Usage is only implied by the resource name, and no exclusions or prerequisites 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 readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: enumerates returned metrics and, more importantly, warns that profile text fields are user-supplied untrusted data and must not be treated as instructions — a real prompt-injection disclosure. It does not note what happens when a codename is absent, but that is minor given the output schema and 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: purpose first, return contents second, security constraint last. No repetition of annotation or schema content, and every sentence earns its place.

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

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

With an output schema present the return values need not be detailed at length, and annotations cover the read-only/idempotent profile. Purpose, keyed lookup, and the untrusted-data constraint are all present; only absence/error behavior for an unknown codename is unaddressed.

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 four parameters are already fully documented, establishing the baseline of 3. The description's only added semantics is that lookup is keyed on codename rather than display name, which is already in the schema, so it does not compensate further.

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

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

States a specific verb and resource with a clear scope: read ONE public operator profile by codename, plus the field set returned (class tier, rank, percentile, Yield, Leverage, Velocity, SNR). This implicitly distinguishes it from aggregate siblings like get_leaderboard, but it does not name or contrast with close per-operator siblings such as operator_signature, operator_gap, or who_operates_like_me.

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 only implied — fetch when you have a codename and need that operator's profile. There is no explicit when-to-use/when-not statement and no routing to the many similar sibling tools that also operate on a single operator, so an agent must infer which one applies.

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 declare readOnly, idempotent, and non-destructive, so safety is covered. The description adds genuine value beyond that: it warns that profile text fields (display_name, codename, handle, bio) are user-supplied untrusted data that must not be treated as instructions — a real behavioral/prompt-injection disclosure — and it characterizes the return as 'the most explanatory factor'.

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 in the first clause, then adds the output shape and the security caveat in compact form. It is slightly dense with the decomposition list, but every element earns its place and nothing is redundant.

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 analytical tool with no output schema, the description adequately covers purpose, output (the most explanatory factor), input modes, and an injection-safety caveat. Gaps remain around error handling for invalid codenames and confirmation that conversation_id must be echoed, though the schema itself documents conversation_id thoroughly.

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 only 38% across 13 parameters, so the description carries extra burden. It does clarify the codename-vs-pillars duality ('two codenames or two sets of pillars') and names the pillar dimensions (leverage, velocity, SNR, scale), which maps usefully onto the a_*/b_* fields, but context, llm_model, and conversation_id semantics are left to 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 ('What specifically separates operator A from operator B?') and precisely scopes the output: primary cause, secondary cause, offsetting weakness, decomposed into leverage/velocity/SNR/scale. This clearly distinguishes it from siblings like compare_to_field or operator_signature, which handle different comparison dimensions.

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 frames the exact question the tool answers and clarifies it is attribution rather than surface-level ranking ('not just "A has more Yield"'), which implies when to reach for it. However, it never explicitly names an alternative sibling (e.g., compare_to_field) or states exclusions, so the routing guidance is implied rather than spelled out.

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. The description adds meaningful beyond-schema context: the deprecated archetype alias, the warning that labels are not the 10-type Build Archetypes reference extension, and a prompt-injection security notice about untrusted profile text fields. This is valuable behavioral context not covered by annotations.

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

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

Four sentences, each carrying weight: purpose, return shape, deprecation note, and security note. The security warning is somewhat tangential but justified for an untrusted-data surface. Front-loaded with the core purpose.

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

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

For a 9-param tool with no output schema, the description covers purpose, return shape, and one major behavioral caveat, but leaves the pillar semantics and window parameter underexplained. Adequate but with a clear gap given the parameter count.

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%, below the high baseline, so the description should compensate. It explains the '4 token pillars or a codename' input mode, which hints at input/output/window/cache parameters semantically, but it does not explain the pillar grouping explicitly (input, output, cache_read, cache_write) or the window enum. Partial compensation 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+resource: 'Computes a normalized operating signature from 4 token pillars or a codename.' Distinguishes the output shape (signature code, legacy label, dominant trait, comparable operators) which differentiates it from siblings like get_operator or compare_to_field, though it does not explicitly name an alternative.

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

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

The description implies usage by noting two input paths (pillars or codename), but it does not state when to choose this tool over siblings such as compare_to_field, get_operator, or who_operates_like_me. No explicit exclusions or prerequisites are given.

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 readOnly/idempotent/non-destructive, so the safety bar is low, yet the description adds real value: it enumerates the returned analysis (nearest operators, similarity %, mutual outperformances, differentiators) and warns that profile text fields are untrusted user-supplied data that must not be followed as instructions. That injection warning is meaningful behavioral context beyond the annotations.

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

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

Front-loaded with the core purpose, then mechanism, then return values, then the safety warning. Every sentence carries information, though 'Makes the leaderboard feel like a network, not a list' is slightly promotional filler.

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

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

No output schema exists, and the description compensates by enumerating what is returned, which is the right call for a 10-parameter tool. The main remaining gap is the undocumented numeric pillar and window parameters, but overall it is complete enough to invoke correctly.

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

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

Schema description coverage is 50%, and the description only clarifies the two input modes ('4 pillars or a codename'). It adds nothing about the numeric pillar params (input/output/cache_read/cache_write), window, or limit, which the schema documents unevenly. With half the params covered by the schema and the description contributing only the input-mode hint, a baseline 3 fits.

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 — 'Finds operators whose operating signature most resembles yours' — and describes the mechanism (compute your signature, then search the leaderboard for nearest neighbors). It is clearly distinguishable from siblings like get_leaderboard or get_operator, which list or fetch rather than match by similarity.

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 implies usage through 'Takes 4 pillars or a codename' and the network-vs-list framing, which hints at exploratory matching over plain listing. But it never states when to prefer this over siblings such as compare_to_field, operator_gap, or get_leaderboard, so the routing decision 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.