periscope-mcp

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

With no annotations, the description carries the full behavioral burden and does add real context: crowd text cannot become evidence because each item declares its own authored tiers, and dry_run stores nothing. It omits idempotency/overwrite behavior on the target corpus and permission requirements for a write operation.

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

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

The purpose is front-loaded in the first sentence, followed by the tiering guarantee and dry_run note. Structurally efficient, with only the README redirect detracting slightly from self-containment.

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, but the payload is a nested free-form object the description defers to src/mcp/README.md, and two path parameters are unexplained. For a tool with nested input and tiering logic, that redirect leaves 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 0% across 5 params, so the description must compensate. It explains payload shape ({"items": [...]}) and dry_run semantics, and references `sections` for tiering, but config_path, periscope_path, and the tiering parameter itself are left undocumented in both schema and description.

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

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

The description uses a specific verb+resource ("Import a user export ... into the evidence corpus") and clarifies the intent versus scraping-based sources. It implicitly distinguishes itself from the read-oriented siblings like ps_corpus_search, though it never names an alternative tool 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?

It gives a concrete when-to-use rule: "Use this for sources Periscope must not scrape," and describes the dry_run preview path as the safe way to test acceptance. No explicit when-not or named-alternative routing is provided, 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?

With no annotations, the description carries the full behavioral burden, and it only discloses that results are ordered by publication recency. It says nothing about pagination, the default limit behavior, auth/config prerequisites, or what the returned items represent.

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?

One short, front-loaded sentence with no filler. It is efficient, though the terseness contributes to the coverage gaps elsewhere rather than being a virtue in isolation.

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

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

An output schema exists, so return values need not be explained, but with zero annotation coverage, four undocumented parameters, and no usage guidance, the description leaves too much for the agent to infer about how to call this 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 0% and four parameters exist, so the description must compensate; it only vaguely gestures at source filtering (likely source_type). The limit, config_path, and periscope_path parameters are undocumented in both the schema and the description.

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

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

The phrase names the resource (items in the corpus), the ordering/scope (most recently published), and an optional narrowing (one source), which implicitly separates it from the search sibling. However, there is no explicit verb and no direct naming of ps_corpus_search as the alternative, so the distinction is inferred rather than stated.

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 at all, and no mention of when to prefer ps_corpus_search or ps_filter_items over this tool. The only hint is 'optionally one source', which gestures at filtering but does not tell the agent when that option is appropriate.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the retrieval algorithm (BM25, CJK-aware), which is useful, but says nothing about ranking, default result count, pagination, or whether config_path/periscope_path change what corpus is searched.

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 tight sentence with no filler, and the core resource is front-loaded. It is efficient, though very slightly under-specified rather than verbose.

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

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

An output schema exists so return values need not be described, but with zero annotation coverage, 0% parameter documentation, and no usage guidance, the definition leaves too much for an agent to infer about scope, limits, and path parameters.

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

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

Schema description coverage is 0% with 4 parameters, so the description must compensate and largely does not. It implies query is a full-text search string, but limit, config_path, and periscope_path receive no explanation in either the schema or the description.

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

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

States a specific verb+resource ('Full-text search over every item ever collected') and adds implementation character (BM25, CJK-aware) that tells the agent what matching behavior to expect. The phrase 'every item ever collected' implies scope beyond the sibling ps_corpus_recent, but no sibling is named explicitly, so differentiation remains implicit.

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 and no alternatives named, despite several plausible siblings (ps_corpus_recent, ps_corpus_import, ps_filter_items, ps_fetch_items). An agent must guess whether to search here or pull recent items elsewhere.

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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose the shape of the output (counts broken down by source, clusters, runs, claims, sessions), which is real value, but it never states that the call is read-only/side-effect free or whether it needs configuration to be valid.

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, zero waste, with the returned-content inventory front-loaded and the usage cue at the end. Every clause 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?

An output schema exists, so return values need not be re-explained, and the description covers the semantic content of the overview well. However, with two completely undocumented optional path parameters, the definition is not quite complete for an agent deciding how to invoke it.

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

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

Both parameters (config_path, periscope_path) have 0% schema description coverage, so the description must compensate and it does not — neither parameter is mentioned. An agent has no guidance on what these paths mean or when to supply them.

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

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

States a specific resource and the content it returns (stored items by source, clusters, runs, plus claim and research-session counters), which clearly distinguishes it as an aggregate-overview tool rather than a retrieval tool. It never names a sibling (e.g. ps_corpus_search) as the alternative, so it stops short of a 5.

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

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

The closing phrase 'The "what do we already know" probe' implies this is a situational-orientation call to make before searching or running research. That is useful implied context, but there is no explicit when-to-use versus when-not, and no alternative is named.

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?

No annotations are provided, so the description carries the full behavioral burden and largely fails. It does not state whether this mutates state (implied by advancing to a new stage), whether it requires network/LLM calls, whether re-running is idempotent, or what auth/run preconditions apply. Only the source→target stage movement is communicated.

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 with no filler, which is structurally clean. But it is sized far below what a 4-parameter pipeline-mutation tool needs, so brevity tips into under-specification rather than efficient conciseness.

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

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

The presence of an output schema relieves the description of explaining return values, but the remaining gaps are large: no annotations, four undocumented parameters, and no description of what enrichment produces or the ordering constraints with ps_filter_items. As a stage-mutating pipeline tool it is significantly under-described.

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

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

Schema description coverage is 0% across 4 parameters, so the description must compensate and does not. The run_id, config_path, and periscope_path parameters are entirely unexplained, and while 'filtered' faintly echoes the source_stage default, the parameter itself is never described.

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?

It pairs a verb (enrich) with a resource (items) and names the target stage (enriched), which loosely distinguishes it from siblings like ps_fetch_items, ps_score_items, and ps_filter_items. However, 'enrich' is undefined jargon — the agent gets no sense of what enrichment actually does to the items. Purpose is identifiable but vague.

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 statement of prerequisites (e.g., that filtering must precede enrichment, or that a run must exist), and no alternatives named. The phrase 'filtered items' implies a sequencing but nothing is explicit. An agent must infer the pipeline position.

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?

With no annotations, the description carries the full behavioral burden, and it discloses almost nothing: it does not say whether fetching is idempotent, how deduplication keys are chosen, whether existing raw items are overwritten, or what permissions/rate limits apply. 'Deduplicate' is the one real behavioral hint, which keeps this above a 1.

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 with no filler, which is structurally sound. It is under-specified rather than bloated, so the size itself is not a defect.

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 five-parameter tool with zero schema coverage and no annotations, the description omits everything an agent needs to call it correctly - source selection, time window semantics, run scoping. The presence of an output schema excuses it from describing return values but not from the input-side 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 description coverage is 0% across five parameters, and the description explains none of them. hours, run_id, sources, config_path, and periscope_path are all opaque from the description; only 'sources' is loosely implied by 'fetch content.'

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 names a verb (fetch) and a resource (content) and scopes it to the 'raw stage,' which hints at its position as the first pipeline stage relative to ps_score_items/ps_enrich_items. However, it never says what content or from where, so it is only loosely distinguishable from sibling ingest-style tools.

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

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

There is no when-to-use guidance, no preconditions, and no mention of alternatives such as ps_corpus_import or ps_run_pipeline. The agent must infer the pipeline position entirely from the phrase 'raw stage.'

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?

With no annotations, the description carries the full burden yet only implies a mutation ('into the filtered stage') without stating whether items are moved, copied, or overwritten, whether the operation is idempotent, or what permissions/run state it needs. No side effects or reversibility are disclosed.

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 short sentence is front-loaded and free of padding, which is good. But at this length it is under-specified rather than concise, leaving no room for the behavioral or parameter context a 6-parameter tool 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 pipeline-stage tool with 6 parameters, no annotations, and 0% schema documentation, the description is far too thin. The presence of an output schema excuses it from explaining return values, but nothing about inputs, ordering, or side effects is covered.

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

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

Schema description coverage is 0% across 6 parameters, so the description must compensate and largely fails. The words 'scored' and 'filter' faintly gesture at the source_stage and threshold concepts, but config_path, topic_dedup, and periscope_path are entirely undocumented in both schema and description.

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

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

It states a specific verb (filter) and resource (items) and names a target stage, so the general action is inferable. However, 'filtered stage' is pipeline jargon with no explanation of what filtering criteria apply, and it does not distinguish itself from pipeline siblings like ps_score_items or ps_enrich_items beyond the stage label.

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 guidance on when this stage should run relative to siblings (e.g., after ps_score_items, before ps_enrich_items), no prerequisites, and no mention of alternatives. The default source_stage='scored' hints at ordering but the description never states it.

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

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

No annotations are provided, so the description carries the full behavioral burden. It is silent on whether the operation writes anything (the save_to_periscope_data flag implies a possible side effect), what permissions are needed, or whether an existing summary is overwritten — all material for a generation tool.

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 single sentence is not padded, but one terse line is under-specification rather than conciseness for a six-parameter tool with side-effect flags. Nothing is front-loaded because there is essentially only one clause.

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

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

An output schema exists, so return values need no explanation, but the description leaves the rich parameter set, side-effect semantics, and relationship to sibling summary/run tools entirely unaddressed. This is inadequate 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 description coverage is 0% across six parameters, and the description explains none of them. Critical fields like source_stage, config_path, periscope_path, and the language default ('zh') are completely undocumented in both schema and description.

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

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

The verb ('Generate') and output artifact ('markdown summary') are stated, giving a rough sense of the operation. However, 'from a stage' is ambiguous and the definition does not distinguish this from the sibling ps_get_run_summary, so an agent cannot confidently pick between 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?

There is no statement of when to use this tool, when not to, or which sibling to prefer (e.g., ps_get_run_summary). The agent is left to infer usage entirely from the name and the stage parameter.

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?

No annotations are provided, so the description carries the full behavioral burden. It lists what comes back but says nothing about permissions, behavior on an unknown claim_id, pagination of evidence rows, or side effects — significant gaps for a tool with zero annotation coverage.

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 phrase with no wasted words. Its brevity borders on under-specification rather than verbosity, but structurally it is clean.

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

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

An output schema exists, so return values need not be spelled out (the description repeats them anyway). For a simple get-by-id tool this is near-adequate, but the undocumented config_path/periscope_path parameters and absence of any behavioral notes leave real 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 description coverage is 0% across three parameters. The description never mentions claim_id, config_path, or periscope_path, so the two optional path parameters are completely undocumented in both schema and description and the agent must guess at their purpose.

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 resource ('one claim') and the payload it returns (verdict, evidence rows, source independence), so an agent knows this is a single-entity detail fetch. It is distinguishable from ps_list_claims by the word 'One', but siblings are never 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?

Usage is only implied: the 'one claim in full' framing suggests calling this after a list/search returns a claim_id. There is no statement of when to prefer it over ps_list_claims or ps_corpus_search, and no prerequisites or failure conditions mentioned.

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?

No annotations are provided, so the description must carry the full behavioral burden. It implies a safe read via 'Read' but discloses nothing about authentication, freshness, rate limits, or whether it is truly non-destructive, leaving a significant gap for a server-facing tool.

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 with zero waste. It is appropriately sized for a simple read tool.

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

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

The presence of an output schema means return values need not be explained. However, with no annotations and many sibling tools that also provide statistics, the description is too thin to fully guide an agent—it never says what 'server metrics' covers or how this differs from corpus or run summaries.

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

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

The tool takes zero parameters, so the baseline is 4 per the rubric. The description adds no parameter information, but none is needed.

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

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

The description states a specific verb ('Read') and resource ('in-memory server metrics'), making the tool's basic function clear. However, it does not distinguish this tool from sibling stats tools such as ps_corpus_stats or ps_get_run_summary, so it falls 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 when-to-use guidance, no mention of alternatives, and no prerequisites or conditions. The sentence only declares what the tool does, leaving the agent to infer when to call it.

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

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

No annotations are supplied, so the description carries the full behavioral burden, and it only conveys the bare implication that "Read" is non-destructive. It says nothing about error behavior for an unknown run_id, whether the run must be complete, or what class of data counts as metadata.

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

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

Three words is technically concise, but this is under-specification rather than efficiency: there is no front-loaded scope, no disambiguation, and no actionable information. Brevity here costs the agent more than it saves.

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 output schema exists, so return values need not be described, but for a tool sitting among many similarly named run-level getters the definition leaves the key question unanswered: what distinguishes this metadata call from run summary, stage, or metrics. It is incomplete for a 27-sibling toolset.

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

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

Schema description coverage is 0% and the single required parameter run_id is documented nowhere. The description could have said where run_id comes from (e.g., ps_list_runs), but it adds no semantics beyond the parameter's self-explanatory name.

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?

It names a verb and resource ("Read run metadata"), so the operation is identifiable, but "metadata" is undefined and the description never distinguishes it from close siblings like ps_get_run_summary, ps_get_run_stage, or ps_get_metrics. An agent cannot tell from the text which of these four run-inspection tools returns what.

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 at all: no statement of prerequisites, no condition under which this tool is preferred over ps_get_run_summary or ps_list_runs, and no exclusions. The agent must infer usage entirely from the name.

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?

With no annotations, the description carries the full behavioral burden. The word 'Read' implies a non-mutating operation, but nothing states pagination/truncation behavior for max_items (default 200), error behavior for invalid run_id or stage, or what happens when a stage is empty or incomplete.

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 short sentence is efficient and front-loaded, but here brevity shades into under-specification rather than disciplined conciseness — the sentence earns its place but leaves obvious room for useful additional detail.

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

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

An output schema exists so return values need not be explained, but with zero annotations, 0% parameter coverage, and an undefined domain term ('stage'), the definition is not complete enough for an agent to call this confidently among 26 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 0%, and the description only loosely echoes two of the three parameter names ('run', 'stage') without adding format, accepted values, or enumeration of valid stages. max_items is entirely unaddressed, so the description fails to compensate for the coverage gap.

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 has a clear verb ('Read') and resource ('items from a run stage'), but never defines what a 'stage' is or which stages exist, which matters given siblings like ps_get_run_meta and ps_fetch_items that operate on adjacent data. It is a plausible but vague purpose, not a tautology.

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 guidance on when to call this instead of ps_fetch_items, ps_get_run_meta, or ps_get_run_summary, nor any stated prerequisites (e.g. run must be in a particular state). The agent must infer usage entirely from the name.

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?

No annotations are provided, so the description carries the full behavioral burden and delivers very little. It implies a read operation but does not disclose whether a summary must be pre-generated, what happens if none exists, language behavior, or any response characteristics.

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 short, front-loaded sentence with no wasted words, which is structurally sound. But its brevity reflects under-specification rather than efficient communication of necessary detail.

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?

Although an output schema exists (so return values need not be described), the description omits the prerequisite relationship to ps_generate_summary, the meaning of the language parameter, and any distinction from peer run getters. For a tool operating in a 26-tool suite with several near-identical getters, this is incomplete.

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

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

Schema description coverage is 0% across 2 parameters, and the description adds nothing: neither run_id nor the language parameter (default 'zh', which selects the summary language) is explained. The description does nothing to compensate for the undocumented 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 ('Read a ... run summary'), so the basic operation is clear. However, it does not distinguish itself from closely related siblings such as ps_get_run_meta, ps_get_run_stage, and ps_get_metrics, all of which are read-only getters on the same run object. The purpose is adequate but not disambiguated.

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

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

The description gives no when-to-use guidance and never mentions the relationship to ps_generate_summary (must a summary exist first?) or to the other run getters. An agent has no criteria for choosing this tool over its siblings.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It lists returned fields but says nothing about read-only safety, required permissions, pagination behavior, or side effects, leaving key behavioral traits undisclosed.

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

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

The description is a single compact sentence with no filler and is front-loaded around the resource and filter. It could be marginally tighter by omitting return-field details that the output schema already covers.

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

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

Given four parameters at 0% schema coverage and no annotations, the description is incomplete. It does not explain most parameters, lacks usage guidance relative to siblings, and omits behavioral context, even though the output schema makes return-value explanation less necessary.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning for the status parameter by listing extracted | linked | graded, but provides no explanation for limit, config_path, periscope_path, or the default of graded, leaving three of four parameters semantically undocumented.

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

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

The description clearly states that the tool lists claims by pipeline status and enumerates the status values, making the core purpose understandable. It does not, however, explicitly differentiate this tool from sibling list/search tools such as ps_get_claim or ps_corpus_search.

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 guidance on when to use this tool versus alternatives. The status filter implies a usage context, but the description never states when to choose it over ps_get_claim, ps_corpus_search, or other list tools.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: it does not state ordering, what 'recent' means (time window? top-N?), pagination behavior, or that results are capped by the limit parameter's default of 20. It is plausibly a read-only list, but that is inferred, not stated.

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 short sentence is front-loaded and contains no filler, which is structurally good. It is terse to the point of under-specification rather than genuinely concise, so it earns only a middle score.

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-value shape need not be explained. But with zero annotations and zero parameter documentation, the description leaves the agent without the scoping, ordering, and limit semantics needed to call this listing tool correctly.

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

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

Schema description coverage is 0% for the single 'limit' parameter, and the description never mentions it, its default of 20, or the maximum. The parameter name is fairly self-explanatory, but the description does nothing to compensate for the coverage gap.

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 has a verb ('List') and a resource ('runs'), plus a vague secondary object ('stage states'), so the general purpose is discernible. However, it gives no basis for choosing it over close siblings such as ps_get_run_meta, ps_get_run_stage, or ps_get_run_summary, and 'recent' and 'stage states' are undefined.

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 conditions, and no mention of alternative tools like ps_get_run_stage or ps_get_run_summary that also expose run information. The reader is left to infer that this is the entry-point listing tool.

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

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

With no annotations, the description carries the full burden. It usefully discloses the control-flow effect (loop resumes, session unparks) and the decline path, which is genuinely beyond the schema. However, it omits auth requirements, idempotency/retry behavior, and what happens if answer is omitted or the request_id is stale.

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, front-loaded with the action and the decline flag, with no filler. It is appropriately short for a control-flow call, though the second sentence is more encouragement than specification.

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

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

An output schema exists, so return values need not be explained. The core interaction is conveyed, but with 6 parameters at 0% schema coverage and no annotations, the definition leaves key invocation details (what answer/request_id should contain, path params) under-specified for a session-driving tool.

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

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

Schema description coverage is 0% across 6 parameters, so the description must compensate and largely does not. It explains only `skip`; `answer`, `request_id`, `session_id`, `config_path` and `periscope_path` carry no meaning beyond their titles, leaving an agent unsure what to pass for the required identifiers.

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?

Names a specific action (reply to a session's question) and its effect (the loop continues), which distinguishes it from generic corpus/pipeline siblings. It does not explicitly contrast itself with near neighbors like ps_research_followup or ps_research_step, so it stops short of a 5.

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

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

It implies the trigger ('a question the session asked') and gives one decision path (`skip: true` to decline), plus the 'how you unpark it' framing. But it never states when to prefer this over ps_research_followup/ps_research_step or what prerequisites (e.g. a parked session, valid request_id) must hold.

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?

With no annotations, the description carries the full burden, and it does meaningful work: it discloses the payload structure, the enumeration of origin values (render | user_edit | merge), and the per-section flags (locked, stale) plus evidence linkage. It stops short of error behavior when a revision is missing or any auth/session requirements, so it is strong but not exhaustive for an annotation-free tool.

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 compact statements, front-loaded with the payload description and ending with the revision default. No filler, and each clause (origin values, section state, evidence ids) 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?

An output schema exists, so explaining return values is not strictly required, yet the description covers them well while leaving the non-revision parameters (config_path, periscope_path) unexplained in an environment with 0% schema coverage and no annotations. Adequate for calling the tool with a session id, incomplete for the full parameter surface.

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

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

Schema coverage is 0% across 4 parameters, so the description must compensate and largely does not. It explains only `revision` ('omit for the latest'); session_id, config_path, and periscope_path get no meaning at all, leaving three of four parameters documented nowhere.

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 (Read) and resource (the research document as a versioned draft) and enumerates what the read yields: revision, origin, and per-section lock/staleness/evidence state. That is well beyond a restatement of the name. It does not, however, distinguish itself from siblings like ps_research_list or ps_research_status, which an agent could easily confuse it 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?

The only usage cue is 'Omit `revision` for the latest,' which is a parameter default hint rather than selection guidance. There is no statement of when to prefer this over ps_research_list or ps_research_status, and no preconditions or exclusions.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: the edit is stored as its own revision, is locked, and a later recompute marks it stale rather than overwriting it. This is genuinely non-obvious and valuable, though it omits any auth/permission or concurrency details.

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 compact clauses with the action front-loaded and the persistence/locking caveat second. Nothing is redundant, though the second clause is carrying a lot in one sentence.

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

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

An output schema exists so return values need no explanation, and the revision/lock semantics are well covered. But for a 5-parameter mutation tool with zero schema descriptions and no annotations, the description leaves parameter meaning and any precondition (session validity, section existence) 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 0% across five parameters, so the schema offers no guidance at all. The description only indirectly hints at section_id ('one section') and body ('your prose') and says nothing about session_id, config_path, or periscope_path, leaving three parameters 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?

States a specific verb and resource: rewriting a single section as the author, which is distinguishable from the sibling generation tools (ps_research_draft, ps_research_answer). However, it never names an alternative explicitly, so the agent must infer the boundary between editing and drafting.

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

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

Usage is implied rather than stated: 'Rewrite one section' suggests it applies to an existing section the author wants to own, but there is no explicit when-to-use condition and no mention of the sibling tools it competes with (ps_research_draft, ps_research_step).

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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose real side effects well – the sub-question tree is revised and the report re-rendered – which is more than most. It omits permissions/auth requirements, whether the revision is reversible or overwrites prior state, and the failure mode if the session does not exist.

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

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

A single tight sentence that is front-loaded with the core action ('push back on an existing session') before the effect clause. No filler, though it packs three behaviors into one sentence.

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

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

An output schema exists, so return values need not be explained, and the mutation behavior is described. Still, for a no-annotation mutation tool the description leaves parameter meaning and sibling discrimination uncovered, so an agent cannot confidently route to it over ps_research_edit/answer.

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

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

Schema description coverage is 0% and there are 4 parameters, so the description must compensate. It adds meaning only for 'message' (narrow/expand/challenge), leaving session_id, config_path, and periscope_path entirely undocumented in both schema and description.

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

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

The description gives a specific verb ('push back on') and resource ('an existing session') and even clarifies the effect: the message can narrow, expand or challenge, and the sub-question tree is revised and report re-rendered. It is clearly a follow-up/refinement tool. However it never names or contrasts with close siblings such as ps_research_edit or ps_research_answer, 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?

'Existing session' and 'push back' imply this is only for continuing an already-started research session, which is useful implicit context. But there is no explicit when-to-use guidance, no exclusions, and no routing to the obvious alternatives (ps_research_edit, ps_research_answer, ps_research_step) that share this niche.

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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: 'recent' hints at default ordering but there is no mention of how results are limited, whether config_path/periscope_path are required for discovery, or pagination behavior. The output schema covers the return shape, which relieves some burden, but scoping and prerequisite behavior remain unstated.

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 short sentence with no filler; it is front-loaded and wastes no words. Its brevity is appropriate structurally, though it is under-specified rather than genuinely concise.

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

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

The output schema covers return values, but for a discovery tool with three undocumented parameters and no annotations, the description leaves the agent without the scoping, ordering, or configuration context needed to call it confidently.

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?

All three parameters (limit, config_path, periscope_path) have zero schema description coverage. The description adds no meaning to any of them — in particular it never explains what config_path or periscope_path are for, which is the most ambiguous part of the schema.

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

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

The phrase names the resource (research sessions) and what it returns (questions, statuses), giving an implied list operation. However it is a noun fragment with no verb, and it does nothing to distinguish itself from siblings like ps_research_status or ps_corpus_recent, which an agent could easily confuse it 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?

There is no statement of when to use this tool versus ps_research_status, ps_research_start, or any other sibling. The agent must infer from the name alone that this is the enumeration entry point.

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?

No annotations exist, so the description carries the full burden. It usefully discloses that this is a long-session task with persistent state and a markdown report return, which matters for an agent. However, it says nothing about cost, latency, permissions, or whether the task is asynchronous vs blocking — significant gaps for a long-running operation.

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

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

Two tight sentences, front-loaded with the core action and the pipeline it triggers. No filler; the persistence note earns its place. Slightly dense but well-structured.

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

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

An output schema exists, so return format needn't be explained, and the description does cover the task lifecycle. But with zero annotation coverage, 0% parameter documentation, and no mention of the two config-path arguments, an agent lacks enough to invoke this long-running tool confidently.

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

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

Schema description coverage is 0% for 3 parameters. The description never mentions config_path or periscope_path, leaving two parameters entirely undocumented in both schema and prose. "question" is inferable from the workflow narrative, but the two config paths are opaque.

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 ("Open a long-session research task") and enumerates the internal workflow (decompose, investigate sub-questions, return a cited markdown report). It is distinguishable from read-only siblings like ps_research_status or ps_research_list, though it never names an alternative to sharpen the contrast.

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 "follow up later, even after restarts" implies this is the entry point that pairs with ps_research_followup, but no explicit when-to-use or when-not-to-use guidance is given. Usage is inferable but not 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?

With no annotations, the description carries the full behavioral burden. It describes the returned session-state contents, but does not explicitly state that the operation is read-only, whether it has side effects, or what permissions are required.

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

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

The description is a single efficient sentence that front-loads the resource and lists the relevant state fields. It is concise, though its terseness leaves several important details unaddressed.

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-value explanation is less critical, but the description still omits usage guidance and all parameter semantics for a 3-parameter tool. For an agent selecting among many research siblings, it is not complete enough.

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

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

The tool has three parameters and 0% schema description coverage, so the description must compensate. It never mentions session_id, config_path, or periscope_path, adding no meaning beyond the bare parameter names.

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

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

The description names the resource and enumerates the session-state contents (sub-question tree, statuses/answers/evidence ids, turn history, rendered report), so an agent can tell this retrieves research-session status. However, it does not explicitly differentiate this tool from siblings such as ps_research_list or ps_research_step.

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

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

The description provides no when-to-use guidance or alternatives. It does not say whether to call this before/after ps_research_step, or how it relates to ps_research_list.

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

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

With no annotations, the description carries the full burden. It does disclose useful traits: one round per call, verb selection, the parking/pending_request behavior, and the delta-only return that keeps cost proportional to changes. It omits auth requirements, error handling, idempotency/re-entrancy semantics, and what happens if the session is already finalised.

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

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

The core action and return shape are front-loaded in the first sentence, and the following sentences add the verb set and payload semantics without much waste. It is slightly dense with parenthetical asides but remains appropriately sized.

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

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

An output schema exists, so return values need not be re-explained, and the description does convey the round/parking model. For a 4-parameter tool with zero schema description coverage and no annotations, however, the gaps in parameter meaning and usage routing leave it short of complete.

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

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

Schema description coverage is 0%, so the description must compensate for all four params, yet it explains none of them. It implicitly references 'the message' (fold the message into the question tree) and mentions pending_request (which is not even a parameter), but session_id, config_path, and periscope_path are entirely undocumented.

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 ('advance a research session by ONE round') and clarifies the scope is a single step returning a delta rather than a full tree. It is clear what the tool does, but it never explicitly names or contrasts the sibling tools (ps_research_followup, ps_research_answer, ps_research_draft) that an agent might confuse it 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?

Usage is implied by the loop semantics: the tool advances a round and may park with a non-null pending_request when input is needed. However, there is no explicit statement of when to call this versus followup/answer/status, nor any prerequisite guidance, 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?

With no annotations, the description carries the entire behavioral burden, and it discloses only the internal stage ordering. It says nothing about side effects, despite a save_to_periscope_data parameter defaulting to false that implies an optional write, nor about runtime, external calls, idempotency, or permissions.

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 single sentence is front-loaded and free of waste, but it is under-specified rather than concise for a nine-parameter pipeline tool with no annotations. Its brevity leaves the agent guessing on nearly every invocation detail.

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

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

An output schema exists, so return values need not be described, but for a nine-parameter orchestrator with zero parameter documentation and no annotations the definition is materially incomplete. Side effects and defaults around persistence (save_to_periscope_data) go entirely unexplained.

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

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

Nine parameters with 0% schema description coverage receive no explanation whatsoever in the description. Only 'enrich' is loosely echoed by the stage list, and nothing clarifies hours, threshold, sources, languages, config_path, topic_dedup, periscope_path, or save_to_periscope_data, so the description fails to compensate for the coverage gap.

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?

Names a specific verb ('Run') and enumerates the composite stages (fetch, score, filter, enrich, summarize), which map cleanly onto sibling tools like ps_fetch_items, ps_score_items, ps_filter_items, ps_enrich_items, and ps_generate_summary. The phrase 'in one call' implicitly distinguishes it from running those stages individually, though it never says so outright.

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 or named alternative; the only cue is 'in one call,' which implies this is the batched shortcut for the individual stage tools. An agent can infer the intent but must guess at prerequisites, cost, or when the single-stage tools are preferable.

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?

No annotations are provided, so the description carries the full burden and carries almost none of it. 'Into the scored stage' hints at a state transition/mutation of a run, but there is no disclosure of permissions, reversibility, side effects, or idempotency.

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?

It is short and front-loaded, but the brevity is under-specification rather than conciseness. Every word is a restatement of the tool name and contributes no actionable 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?

Even though an output schema exists (removing the need to document return values), the definition provides no annotations, no parameter semantics, and no usage context for a four-parameter pipeline tool. An agent cannot reliably decide when or how to invoke it from this description.

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

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

Schema description coverage is 0% across four parameters (run_id, config_path, source_stage, periscope_path), and the description says nothing about any of them. The defaults 'raw' and null behavior are equally unexplained, so nothing compensates for the coverage gap.

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 restates the tool name with a circular phrase: 'Score a stage into the scored stage.' It never says what scoring means, what gets scored, or what items (ps_score_items) have to do with stages. It names a verb and a noun but no meaningful resource semantics.

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 and no reference to any alternative. The mention of 'stage' faintly implies membership in a pipeline workflow that includes siblings like ps_run_pipeline or ps_get_run_stage, but nothing tells the agent when to pick this tool over them.

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?

With no annotations, the description carries the full burden, and it does disclose important behavior: the webhook URL comes from an environment variable, headers/body template come from the Periscope config, and template variables are substituted in both URL and body before sending. However, it omits failure behavior, what happens if the URL or config is missing, auth requirements, and whether the call blocks or retries.

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 that front-load the action and then the mechanics; the parameter list is dense but earns its place given 0% schema coverage. Minimal filler, though the second sentence packs a lot into one clause.

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

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

An output schema exists, so return values need not be described. But for a side-effecting external notification with no annotations, the description should cover failure modes and the unresolved config_path/periscope_path parameters; it does enough to call the tool but not enough to predict its behavior.

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

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

Schema coverage is 0%, so the schema provides no parameter meaning, and the description compensates by naming most substitution variables (#{date}, #{language}, #{important_items}, #{all_items}, #{result}, #{summary}) and explaining that they are replaced in URL/body. It leaves config_path and periscope_path completely unexplained (and #{timestamp} has no matching parameter), so it only partially covers 8 undocumented params.

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 combination ("Send a webhook notification") and clarifies that it uses a configured URL, request_body template, and headers. It is unambiguous about what the tool does, though it does not differentiate itself from any sibling (no sibling handles webhooks, so the ambiguity risk is low).

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 guidance on when to use this tool versus alternatives, no prerequisites stated as conditions, and no exclusions. The mention of config/env-var sourcing implies a setup requirement but never tells the agent under what circumstances to invoke it.

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

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

No annotations are provided, so the description carries the full behavioral burden. It states what is checked but not how failure is surfaced (exception vs. error list), whether anything is mutated on disk, or whether env-var checks can be skipped; the only behavior hint, check_env, lives in the schema rather than the prose.

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 with no filler. It is appropriately sized, though its brevity is partly under-specification rather than economy.

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

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

An output schema exists, so return values need not be described, but with zero annotation coverage and 0% parameter documentation the description leaves an agent without enough context to invoke the four optional arguments meaningfully or to anticipate the tool's behavior.

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

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

Schema description coverage is 0% for four parameters. The phrase 'config' loosely hints at config_path and 'environment variables' at check_env, but 'sources' and 'periscope_path' are entirely unexplained in either place, so the description does not compensate for the coverage gap.

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+resource ('Validate Periscope config') and expands scope to 'required environment variables'. It is unambiguous what the tool does, though it makes no attempt to relate itself to any sibling (none of the siblings overlap, so differentiation is less critical here).

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 indication of when to run this tool, e.g. before ps_run_pipeline or after changing config, and no prerequisites or alternatives are named. The reader must infer usage entirely from the name.

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