Chertov & Vorobyov physics problem solutions

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

Beyond the readOnly and idempotent annotations, the description discloses the full response shape, the not_found/not_solved variants, and the critical behavioral note that a missing or unsolved problem is a normal result and should not be retried. This adds meaningful context the annotations don't provide.

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

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

Every sentence earns its place: purpose, addressing syntax, return format, and edge-case semantics are all covered with no filler. The critical 'do not retry' guidance is delivered succinctly.

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 there is no output schema, the description fully documents the return values and both found and not-found cases. It also covers the mutually exclusive parameter usage, making the tool safely callable without additional context.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds value by explaining that label is an alternative to paragraph + number, and by clarifying accepted spoken/written forms such as '1.12', '1-12', and '1 12'.

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 ('Returns') and resource ('One solved problem, in full'), making the tool's purpose unmistakable. It also implicitly distinguishes itself from the list/search siblings by focusing on a single solved problem retrieval.

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

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

The description provides clear guidance on how to address a problem: either with paragraph + number or with a label, including accepted spoken forms. It doesn't explicitly name sibling alternatives or exclusion conditions, but the exact-lookup context is clear.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the tool's safe, read-only nature is covered. The description adds value by disclosing the exact JSON return shape, including chapters and totals, which is especially useful because no output schema is provided.

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 compact and front-loaded, starting with the essential purpose, then the return structure, then usage guidance. Every sentence contributes meaningfully 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 zero-parameter read-only tool, the description is complete: it states what the tool returns, the exact JSON shape, and when to call it. Since there is no output schema, including the return structure is especially valuable.

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, and the description explicitly confirms it takes no arguments. This meets the baseline for parameterless tools and leaves no ambiguity about invocation.

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

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

The description clearly states that the tool lists every chapter of a specific physics problem book with paragraph numbers and solved-problem counts, which distinguishes it from siblings like list_problems and list_paragraphs. The verb 'list' and the resource 'chapters' are unambiguous.

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

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

The description explicitly says to call this tool first to learn the shape of the corpus, giving clear contextual guidance. It does not explicitly describe when not to use it, but the 'call this first' instruction strongly implies its role relative to the sibling 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?

Annotations already establish readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations by specifying the exact JSON return shape and the globally unique nature of paragraph numbers, which clarifies how results can be addressed.

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 efficiently structured: what the tool does, the argument, the return shape, and a key uniqueness note. Since there is no output schema, the detailed JSON listing earns its place and is not redundant.

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

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

With no output schema, the description fully compensates by enumerating all returned fields and totals. It also explains optional filtering and the significance of unique paragraph numbers. Nothing essential is missing for an agent to call the 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?

The only parameter, chapter, has 100% schema description coverage, including the crucial 'Omit for every paragraph' instruction. The description merely repeats 'chapter (optional integer)' without adding semantic detail beyond the schema, so the baseline score applies.

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

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

The description opens with a specific verb and resource: "Paragraphs (§) of the problem book, optionally restricted to one chapter." This clearly identifies what is listed and distinguishes it from sibling tools like list_chapters and list_problems, while the mention of unique paragraph numbers reinforces the resource identity.

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

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

The description provides clear context for when to use the tool: list paragraphs, with an optional chapter restriction. It also clarifies the omission behavior through the schema description ('Omit for every paragraph in the book'). It does not explicitly discuss alternatives or when not to use this tool, 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?

Beyond the readOnly and idempotent annotations, the description discloses important behaviors: problems without solutions are excluded and not counted, solutions exist only as GIFs at solution_image_url, and results are in book order. These details materially shape how the agent should interpret results.

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

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

The description is front-loaded with the core behavior and then provides dense, relevant API details. Every sentence earns its place, especially the return-shape documentation, since there is no output schema.

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

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

With no output schema, the description fully documents the JSON response structure, field meanings, pagination, and filtering behavior. Nothing an agent needs to call the tool or interpret its result is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates defaults and max values but adds little semantic meaning beyond the schema; the useful extras concern output field meanings rather than parameter behavior.

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 solved problems of a specific paragraph (§), paginated and in book order. The qualifier 'Solved' and the paragraph scope differentiate it from siblings like list_chapters, list_paragraphs, and search_problems.

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 intended use is implied by the opening phrase and the schema points to list_paragraphs for paragraph numbering, but the description does not explicitly state when to prefer list_problems over get_problem or search_problems, nor 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?

Annotations already signal read-only and idempotent behavior. The description adds meaningful behavioral detail beyond that: short queries are rejected with a validation error rather than returning empty results, LIKE wildcards are treated literally, and only problem statements are searched. This gives agents reliable expectations about edge-case behavior.

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

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

The description is dense but efficient: it front-loads the core purpose and scope, then covers parameters, return shape, language, and validation behavior without filler. Every sentence adds actionable information for an agent.

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

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

With no output schema, the description compensates by spelling out the exact JSON response shape, including pagination fields and per-problem fields. Combined with parameter details and error behavior, an agent has everything needed to construct a correct call and interpret the response.

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

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

Schema description coverage is 100%, so the schema already documents query length requirements, defaults, and bounds. The description mostly restates these details rather than adding new parameter meaning. It does reinforce important behavior, but the schema already carries the semantic load.

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

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

The description opens with a specific verb and resource: 'Full-text search over the Russian problem statements.' It further distinguishes itself by explicitly stating it searches 'PROBLEMS ONLY — never articles or news,' which separates it from any broad content search and from sibling list/retrieval 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 clearly communicates when to use the tool—when a full-text keyword search over problem statements is needed rather than retrieving or listing known problems. It also gives practical constraints: query must be Russian and at least 5 non-whitespace characters. It does not explicitly name alternative tools, 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.