PJQ — Public Judgment Quotient

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

In the absence of annotations, the description explains the meaning of the controversy score (1.0 = 50/50 split) and documents parameter constraints (limit range, days max age). However, it doesn't mention sorting order or response shape, which are partially covered by the output schema.

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

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

Three sentences with no filler. Each sentence adds a distinct piece of information: purpose, usage context/differentiation, and parameter documentation. Front-loaded with the main purpose.

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

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

Given the simple two-parameter tool, the description covers purpose, metric definition, parameter constraints, and differentiation from alternatives. The output schema covers return structures, so no additional return documentation is needed. Minor gaps like sort ordering are 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?

The input schema has 0% description coverage, but the description fully explains both parameters: limit (1..20, default 5) and days (max age, default 30), adding range and meaning beyond the schema types/defaults.

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 returns the most controversial videos, defines the controversy metric (SUP/AGA split 0..1), and explicitly distinguishes it from mood_net (direction vs magnitude). This leaves no ambiguity about the tool's function.

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 provides a specific use case ('for finding topics with maximum opinion split') and explicitly contrasts with mood_net, explaining the difference between direction and magnitude. This gives clear guidance on when to choose this tool over alternatives.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states that the tool returns the last `limit` snapshots with calculated metrics, which is a clear behavioral trait. However, it does not detail filtering semantics (e.g., null means no filter), error handling on invalid values, or potential rate limits, leaving some transparency gaps.

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

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

The description is concise and well-structured: a single overview sentence followed by compact lists of valid domain and tier values, and a clear statement of what the tool returns. There is no unnecessary jargon or repetition, making it easy to parse.

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

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

For a tool with three optional parameters and an output schema present, the description provides the essential information for correct invocation: valid enum values for the filters and the meaning of the limit parameter. It appropriately leaves return-value details to the output schema and does not over-explain simple behavior, though it could mention that domain and tier are optional filters.

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

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

The schema has 0% description coverage, so the description must compensate. It does this by listing all allowed values for `domain` and `tier`, and by explaining that `limit` controls the number of returned snapshots. This adds meaning beyond the bare schema, although it does not mention that filters are optional (the default null implies this).

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

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

The description clearly states the tool returns an 'aggregate mood view' with domain and tier filters, and specifies it returns the last `limit` snapshots with computed mood_net and support_pct. The verb 'returns' and the resource 'mood snapshots' are explicit, and it is distinct from the sibling video-related tools.

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

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

The description implies the tool is for retrieving aggregated mood data with optional filters, but it does not explicitly state when to use it over alternatives or when not to use it. Since all siblings are video-related, there are no direct competing tools, but the description itself offers no usage context beyond its functional purpose.

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 discloses the 10-20 minute runtime, the two-stage pipeline (haiku + sonnet QA), side effects (writes to SQLite and Obsidian), return format (verdict_id + summary with hard_counts, mood, QA-stats), and the public server limitation. This is exemplary behavioral transparency.

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

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

The description is well-structured and front-loaded: summary, warning, parameter guidance, return summary, and deployment note. Every sentence is informative, with no wasted words.

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 complex tool with no annotations and no shared schema details, this description covers operation duration, side effects, parameter tradeoffs, return structure, and deployment status. It gives an agent sufficient context to decide when and 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?

Schema description coverage is 0%, so the description must compensate. It explicitly explains `qa` and its effect on speed and metrics. The `url` parameter is clear from 'URL -> вердикт', but its format is not specified, so minor gap remains.

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

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

The description opens with 'Полный pipeline: URL -> вердикт в SQLite + Obsidian vault,' which precisely states the tool's function as a pipeline from a URL to a verdict stored in two destinations. This clearly distinguishes it from sibling read-only tools like videos_list and video_verdict.

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 warns about the long runtime and explicitly explains the `qa` flag tradeoff, giving clear conditional guidance on when to use `qa=False`. It also notes the public server unavailability via env flag. It does not explicitly name alternatives, but the sibling list implies separate roles.

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 burden of disclosing behavior. It adds useful context about operating on the latest snapshot and the uniqueness of comment text storage, but does not explicitly state whether it is read-only, require permissions, or describe output structure (though output schema exists).

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 three sentences, front-loaded with the primary action, and every sentence adds value (purpose, filtering, uniqueness). No filler or redundancy.

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

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

Given the simple parameter set (2 params) and the presence of an output schema, the description covers the essential context: what the tool does, the filtering option, and a critical note about comment text storage. It is sufficiently complete for the tool's complexity.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the stance parameter with valid values (SUP/AGA/NEU/OFF/THIN/SUS/AGN) and that it filters results. video_id is implicitly clear as the key for lookup. This adds meaning beyond the bare schema.

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

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

The description clearly states the tool retrieves exemplar quotes from the latest snapshot by video_id, with optional stance filtering. It also distinguishes itself by noting it is the only place comment text is stored, which separates it from sibling tools like video_classify or video_verdict.

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

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

The description gives clear context that this tool should be used when comment text is needed, explicitly stating 'Это единственное место, где хранится текст комментариев.' It also explains the stance filter behavior, but does not explicitly mention when to avoid it or compare to alternatives directly.

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. It discloses the ordering (from old to new) and the fact that it returns all snapshots, but does not mention potential errors, rate limits, or that it is read-only. This is adequate for a simple read-only tool but lacks deeper behavioral detail.

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

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

The description is two concise sentences, front-loaded with the main behavior and then a brief use case. Every sentence adds value with zero 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?

Given the tool has only one parameter and an output schema exists, the description covers the essential behavior, ordering, and a use case. It could mention edge cases or what a snapshot contains, but the output schema likely covers the return structure.

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 sole parameter video_id is described contextually as the key for filtering snapshots. With 0% schema description coverage, the description compensates by clarifying that the parameter identifies the video whose history is being retrieved.

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 it returns all snapshots for a video_id over time, ordered from old to new. This specifies the verb (retrieve history), the resource (snapshots), and the scope (video_id), distinguishing it from siblings like video_verdict or videos_list.

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

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

It explicitly provides a use case: analyzing the dynamics of mood over time. This gives clear context for when to use the tool, though it does not explicitly exclude any alternatives or mention when not to use 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?

The description discloses the return fields (id, external_id, title, channel_name, domain, tier, first_seen), which is useful. However, with no annotations provided, it does not explicitly state that this is a read-only operation or mention any potential limitations like pagination or size constraints.

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, front-loaded sentence that states the purpose and lists output fields. Every part is informative and there is no filler or redundancy.

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

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

For a simple list tool with no parameters and an existing output schema, the description is adequate. It does not explain the meaning of 'canon' or any limitations, but the lack of parameters and the straightforward nature of the operation make it reasonably 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?

The tool has zero parameters, so the input schema is empty. The description adding field names is not about parameters, but since there are none, the baseline of 4 applies. The description does not need to compensate for parameter documentation.

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 the tool lists 'Все видео из канона' (all videos from the canon), specifying a clear verb+resource and scope. It also lists the output fields, distinguishing it from siblings like 'controversial_videos' which likely returns a filtered subset.

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 guidance on when to use this tool versus alternatives such as 'controversial_videos' or 'video_classify'. It neither mentions exclusions nor directs users to other tools for filtered views, leaving the decision to the agent.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It implies a read-only operation ('latest snapshot') but does not explicitly state absence of side effects, authorization requirements, or other behavioral traits. This is insufficient for a tool with zero annotation context.

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

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

The description is front-loaded with a clear purpose sentence, followed by a structured list of returned fields. Every sentence adds value, with no fluff or redundancy.

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

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

The tool has a simple one-parameter schema and an output schema present, but the description still enumerates the returned fields in detail, making it self-contained. It lacks usage alternatives, but that is covered under a separate dimension. Overall, it is sufficiently complete for its simplicity.

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

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

The schema only defines video_id as a string, but the description adds the semantic constraint 'YouTube video_id (11 симв.)', providing format validation (11 characters). This meaningfully supplements the 0% schema coverage.

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

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

The description clearly states the tool returns the latest verdict snapshot for a YouTube video_id, with a specific verb and resource. It distinguishes from siblings like video_history (which likely provides historical data) by emphasizing 'latest snapshot' and enumerates the exact output fields.

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

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

No guidance is provided on when to use this tool vs. alternatives such as video_history or video_classify. The description only explains what it returns, not the appropriate context or exclusion criteria.

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