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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's value is in the details it adds: default ordering (newest first), page size (10 per page), what each mode returns (excerpt and categories vs. article text), and the 6,000-character truncation with a pointer to the url for the remainder. The truncation disclosure is a real behavioral trait an agent could not infer from annotations or schema. Minor gap: page bounds (1–100) are only in the schema, not reinforced here.

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, no filler. The resource identity is front-loaded, then the two modes are given in the order an agent would consider them. Every clause carries information: domain, ordering, page size, return fields, truncation cap.

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?

There is no output schema, so the description carries the burden of describing returns, and it does: listing yields excerpt plus categories, reading yields article text capped at 6,000 characters with the url for the rest. Combined with annotations covering safety and a fully documented schema, an agent has everything needed 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 coverage is 100%, so the baseline would be 3, but the description goes further by explaining the semantic switch that the schema only hints at: slug present changes the operation from listing to reading a full article. It also implies search and category are listing-only via the 'list only' schema notes, matching the description's framing. It stops short of giving format examples for search terms or slug syntax.

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 specific pair of verbs (search, read) and a specific resource (the Quera blog at quera.org/blog), plus the content domain (Persian programming, career and tech articles). Against siblings like qr_jobs, qr_problems and qr_courses, the resource is unmistakable, and the two operating modes (list vs. single article) are both 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?

It clearly states the mode-selection rule: omit slug to list, supply slug to read an article, which is exactly the when-to-use guidance an agent needs for this tool. It does not mention any exclusions or alternative tools, though the siblings are different resources rather than substitutes, so the omission is minor.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety bar is low; the description adds real context beyond them — default scope excludes closed cohorts, the slug mode returns materially richer data, and prices are denominated in Toman. It does not discuss pagination or result-size limits, which matters somewhat for an openWorld listing 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?

Front-loaded with the resource and payload, then a compact mode-by-mode breakdown and a one-line currency note; almost no waste. Minor friction from 'or get one in full' appearing before the modes are explained, which forces a short backtrack.

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?

There is no output schema, so the description must carry the return-value burden — and it does, describing both the list payload and the full detail payload. Combined with annotations covering safety and idempotency, an agent has everything needed to choose a mode and call it correctly.

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

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

Schema coverage is 100%, so both parameters are already documented, making 3 the baseline. The description does add value by spelling out what the slug mode returns (syllabus, prerequisites, instructors, installments, FAQ) and by framing include_closed as 'adds past ones', but it adds little on slug format beyond the schema's example.

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 ('List Quera's intensive paid bootcamps') plus a second mode ('get one in full'), and enumerates the returned fields (price, dates, seats). An agent can distinguish the list form from the single-item form without opening the schema.

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

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

Explicitly splits the two usage modes: 'Without slug: cohorts you can register for now' and 'With slug: syllabus by week...'. It also names the modifier that changes scope ('include_closed adds past ones'). It stops short of naming alternatives among siblings (e.g. qr_courses) for when a bootcamp is the wrong resource.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds genuinely new behavior: a fixed page size of 15 and the fact that each result carries an open_jobs posting count. It stops short of describing other returned fields or what happens with an out-of-range page, but the added context is real.

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 plus a routing clause, with the identity of the resource front-loaded and the sibling pointer last. No filler and nothing repeated from the schema or annotations.

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 carries the burden of explaining returns and does so partially (page size, open_jobs count), which is enough for an agent to call it correctly. The remaining gap is the full result shape beyond those two facts, a minor omission for a simple filtered list.

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

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

Schema description coverage is 100%, so all six parameters are already documented, and the description only paraphrases the filter dimensions ('name, city, size or tech stack'). It adds no syntax, format, or defaulting guidance beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Search the 3,000+ companies with a Quera Magnet profile'), gives the corpus size, and distinguishes itself from the sibling qr_company by being the search/list endpoint rather than the profile endpoint. An agent can tell immediately what it returns.

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

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

'Use to find employers by name, city, size or tech stack' names the trigger conditions, and 'call qr_company for the profile and its jobs' explicitly routes the agent to the correct sibling when detail rather than search is wanted. Both the when and the when-instead are present.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds the concrete return contents (profile sections + jobs list) and the chaining behavior that annotations cannot express. It does not cover failure behavior for an unknown slug, which keeps it from a 5.

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 sentences, no filler, with the payload definition front-loaded and the workflow hint second. Every clause carries information an agent would otherwise have to guess.

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 single-parameter, read-only lookup with rich annotations and no output schema, the description covers what the tool is, what comes back, and where the input comes from. Only the error case for an invalid or unknown slug is left unaddressed.

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

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

Schema description coverage is 100% and the schema already says the slug comes from qr_companies or qr_job with an example. The description adds no new syntax, format, or constraint detail beyond that, so the baseline 3 applies.

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

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

States a specific verb ('Get') and resource ('a company's Quera profile') and enumerates the payload fields (about, size, industry, tech stack, benefits, contacts) plus open jobs. That level of detail separates it cleanly from qr_companies, which by name is the listing counterpart.

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?

'Call after qr_companies or qr_job' gives an explicit prerequisite and ordering, and 'The jobs list has ids for qr_job' explains the downstream handoff. It stops short of stating when-not to use it (e.g. slug-only lookup vs name search), so it is not a full 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?

The annotations already state readOnly, idempotent, and openWorld. The description adds behavior the annotations do not provide: page size (10 per page), sort order (newest first), the default result mix, and the fact that times use the UTC ISO format. It says nothing about rate limits or error cases, but for a read-only listing tool these details are enough.

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 has three tight sentences that are front-loaded with the primary no-filter behavior, followed by the category mode and a short note on data format. The fragments 'Times are UTC ISO' and 'Rankings and user profiles are not offered' earn their place, though they read slightly as notes.

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 four optional parameters, no output schema, and read-only annotations, the description covers what is needed: what each mode returns, page size and ordering, timestamp format, and what data this tool omits. Only hints about the result shape (fields per contest) are absent, which is a minor gap.

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 3 is the baseline. The description still adds meaning beyond the schema: paging applies only when a category is provided, and results are 10 per page in newest-first order, which the `page` schema does not say. It does not explain organizer or contest_type semantics, but the schema already covers those.

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 precise verb-and-resource pair: 'List Quera programming contests'. It also describes how the default behavior differs from the filtered behavior. It does not explain how this tool differs from close siblings such as qr_event, qr_bootcamps, or qr_courses, but it does set a clear boundary by saying that rankings and user profiles are not offered.

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 clearly explains the two ways to use the tool: call it with no filter to see what is running, upcoming, or recently finished, or pass a category to page through that topic's archive. That is concrete when-to-use guidance. It does not say when to avoid this tool or which sibling to use instead, so the exclusions are limited.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely useful non-annotation context: the two price fields' meaning (list price vs current price, 0 = free) and the fact that upcoming courses are returned separately. It stops short of describing ordering/pagination of 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?

Front-loaded with the resource and scope in the first sentence, then price semantics, then the sibling routing line. Roughly 60 words with no filler, though the price sentence is slightly dense in phrasing.

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

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

With no output schema, the description usefully names the returned fields (level, price) and warns that upcoming courses are listed apart, which an agent needs to parse results. For a four-optional-param read-only listing tool this is close to complete, though result ordering/shape could be clearer.

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

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

Schema description coverage is 100%, so all four parameters (level, order, track, search) are already documented with enums and examples. The description adds no further filtering semantics; its price notes describe return values rather than inputs. Baseline 3 applies.

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

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

States a specific verb and resource ("List Quera College's paid programming courses"), scopes it with a count (~70) and returned attributes (level, price), and explicitly names the sibling it is not (qr_bootcamps). An agent can distinguish it from the other qr_* listing tools without opening the schema.

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

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

Gives an explicit use case ("Use for 'which Quera course teaches X'") and an explicit routing rule to an alternative ("For intensive bootcamps call qr_bootcamps"). The remaining siblings (jobs, blog, problems) are different domains and need no exclusion.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds genuinely non-annotated behavior: the categories of data the page yields and, more usefully, the data categories explicitly absent (participant lists, rankings), which prevents misdirected calls. It does not discuss pagination or response shape, but with no output schema the content enumeration compensates well.

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 with zero filler: the first front-loads what the tool returns, the second front-loads the ordering constraint and the exclusion. Every clause carries information the agent needs.

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

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

For a single-parameter, read-only fetch with no output schema, the description is nearly complete: it names the resource, the returned content categories, the prerequisite call, and the unavailable data. The only minor gap is any hint about response size or pagination, which is unlikely to matter for a single page fetch.

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% and the slug property description already explains provenance ('Event slug from a qr_contests url ... e.g. codecup8-algorithm'). The description's 'Call after qr_contests' reinforces that provenance but adds no new syntax, format, or validation detail beyond the schema, so the baseline 3 applies.

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

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

The description uses a specific verb ('Get') with a concrete resource ('Quera event or competition page') and enumerates the content types it covers (CodeCup, hackathon, contest series) plus the fields returned (schedule, prizes, price, sub-events). This clearly separates it from the listing-oriented siblings such as qr_contests and qr_problems, though the differentiation is only implied via the sequencing note rather than stated 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?

It gives an explicit sequencing rule ('Call after qr_contests') that tells the agent when in a workflow to invoke it, and an explicit exclusion ('Participant lists and rankings are not offered') that prevents a doomed call. It stops short of naming an alternative tool for those excluded data types, so it is clear context rather than full when/when-not routing.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is fully covered. The description adds that the response includes related jobs and a full detail set, which is real value, but it says nothing about rate limits, errors for unknown ids, or output shape.

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, the payload description front-loaded, and the follow-up workflow note second. Nothing is redundant.

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

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

With no output schema, the enumeration of returned fields usefully compensates, and the read-only annotations remove mutation risk from consideration. Only edge behavior (invalid id, missing job) is left 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 coverage is 100% and the single 'id' parameter already carries its format and an example ('wxvdk'). The description adds no further constraint on the id, so the schema does the work and the baseline 3 applies.

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

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

States a specific verb and resource ('Get one Quera job posting') and enumerates the payload (description, requirements, benefits, skills, salary, deadline, related jobs), which makes it distinguishable from the sibling listing tool qr_jobs.

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?

'Call after qr_jobs' gives explicit sequencing, and 'Use qr_company with the company slug for the employer's profile' routes the agent to the right sibling for a related need. It never states an exclusion for this tool itself, so a 4 rather than a 5.

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

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

Annotations already cover readOnly/idempotent/destructive, so the description is free to add the genuinely non-obvious fact that the tech-code list is not a closed enum ("Any tech code works, not only these"). It also signals the call is safe to make once for discovery, which shapes agent behavior. It stops short of saying whether values come back as ids, names, or both.

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: contents first, usage condition second. No boilerplate, no repetition of the title, and the caveat about tech codes is placed where it will actually be read.

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 correctly carries the burden of describing return content by enumerating the five value categories. What an agent still cannot predict is the shape of each entry (flat string list vs id/label objects), which for a zero-param discovery tool is a minor but real gap.

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 no parameters, so there is nothing for the description to disambiguate; baseline applies. The mention of "industry id" is a small bonus, hinting at the identifier form used elsewhere.

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 (list) and resource (filter values) and names exactly which siblings consume them (qr_jobs, qr_companies), plus the five value categories returned. An agent can distinguish it from qr_problem_filters without opening either schema.

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

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

"Call once when unsure which city, industry id or technology code to use" gives an explicit trigger and implies idempotent reuse rather than repeated calls. The one gap is that it never routes to the sibling qr_problem_filters for problem-side filters, so that boundary is left to inference.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavior: fixed page size of 15, salary denominated in Toman per month and only present when the employer published it, and the AND semantics of combining filters.

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

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

Three short blocks with no filler, and the most important facts (what it searches, page size, follow-up call) are front-loaded. Every sentence carries operational information.

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

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

For an 11-parameter, zero-required search tool with no output schema, the description covers page size, result shape (id plus salary), and currency. It leaves minor gaps such as how result ordering interacts with paging or whether a total result count is returned, but nothing that would cause a mis-call.

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 parameter schema already carries the burden, and the correct baseline is 3. The description adds one useful piece of cross-parameter semantics ('Filters combine with AND') but does not explain how the free-text 'search' parameter interacts with the structured filters such as technologies or level.

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 and resource ('Search the open tech jobs on Quera Magnet') plus a scope detail (15 per page), and explicitly separates itself from the sibling detail tool by saying each result's id should be passed to qr_job. An agent can distinguish it from qr_job and qr_job_filters without opening any schema.

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

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

Gives two concrete example intents ('junior Python jobs in Tehran', 'remote DevOps roles') and a clear follow-up path to qr_job for full descriptions. It does not explicitly say when to reach for qr_job_filters first or when not to use this tool, so it stops short of full when/when-not coverage.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds genuine context beyond them: the statement is Markdown with LaTeX, and no write/submit action is available here, which prevents an agent from attempting a submission through this tool. It does not cover behavior on an invalid or missing id, which keeps it from a 5.

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 blocks: the payload enumeration is front-loaded, then a single line of routing and scope guidance. Every sentence carries information, with no restating of the name or title.

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 one-parameter read tool with full annotation coverage, the description supplies the one thing structured data lacks: no output schema exists, and the description compensates by enumerating the returned fields and their format. Required context for correct invocation is present.

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

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

Schema description coverage is 100% and the single parameter already documents itself as "Problem id from qr_problems, e.g. '589'". The description adds no additional syntax, format, or constraint meaning for the id, so this is the baseline 3 case where the schema does the work.

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 ("Get one Quera problem") and enumerates exactly what the record contains: statement in Markdown with LaTeX, limits, difficulty, tags, solve stats and languages. The singular "one" implicitly separates it from the sibling list tool qr_problems, so an agent can distinguish it without opening either schema.

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

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

Gives explicit sequencing guidance ("Call after qr_problems"), which tells the agent where the id comes from and establishes the correct call order for a detail fetch. It also adds a scope exclusion ("Submitting solutions is not possible here"), but does not name what to use instead for solving, so it stops short of full alternative routing.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds that the call is a one-time reference lookup ('call once') and enumerates the four categories of values returned, which is useful context given there is no output schema.

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

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

Two short sentences with no filler: the first states what is returned, the second states when to call it. The content is front-loaded and every clause carries information.

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

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

For a zero-argument reference tool with no output schema, the description gives the return categories and the calling condition, which is largely sufficient. It stops short of describing the shape of the response (e.g., flat lists vs. keyed by category), a minor gap given no output schema exists.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline applies. The description does not waste space restating a schema that has no properties.

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: it lists the topic slugs, contest ids, origins and judging types accepted by qr_problems. An agent can immediately tell this is a reference/enumeration lookup and distinguish it from qr_problems, which actually queries 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?

It gives explicit when-to-use guidance ('call once when unsure which tag or contest value to use in qr_problems'), tying invocation to a concrete decision point. It does not name what to do instead when the value is already known, but the routing is clear from the phrasing.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new operational context: the corpus size (~2,000 problems) and the fixed page size of 25, which an agent needs in order to reason about pagination. It does not describe result fields beyond 'id', which keeps it from a 5.

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

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

Three short lines, front-loaded with the corpus scope and page size, then usage, then the follow-up call chain. No sentence is redundant and nothing is buried.

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 seven-parameter, all-optional search tool with no output schema, the description covers what the agent needs: what is searched, page granularity, how to obtain valid slugs and contest ids, and how to get from a result to a statement. The only gap is the shape of the result objects apart from 'id', which is left implicit.

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 explains tag, page, order, search, contest, category and difficulty, including the pointer to qr_problem_filters. The description only echoes the filtering dimensions ('topic, difficulty or name') without adding format or constraint detail beyond the schema. Baseline 3 is appropriate when the schema carries the semantics.

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 ('Search Quera's public problemset') plus scope ('about 2,000 programming problems, 25 per page'). It also distinguishes itself from the sibling qr_problem, which is the tool for the actual statement, so an agent can route without opening either schema.

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

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

Explicitly says to use it 'to find practice problems by topic, difficulty or name' and names two alternatives with their roles ('qr_problem' for statements, 'qr_problem_filters' for valid slugs and contest ids). It stops short of stating when NOT to use it, e.g. browsing contests or courses, so it is clear context rather than full routing logic.

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 read-only, idempotent, non-destructive behavior, and the description adds genuinely new context: the coverage bias (only salary-showing postings), the unit and period, and the aggregation grouping. It does not disclose the aggregation statistic itself — median vs. mean vs. range — which materially affects how the numbers should be reported.

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

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

Three short sentences, each doing distinct work: what it returns, when to use it with a caveat, and where to drill down. The core output definition is front-loaded with no redundant restatement of the title.

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 carries the burden of describing returns and it does specify grouping and unit, which is the essential shape. It stops short of describing the statistic or output fields, so an agent still cannot predict exactly what numbers it will receive.

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 parameters are already documented, including the any-of semantics for technologies and the enum values for level. The description adds only the output unit and the cross-reference that city behaves 'as for qr_jobs,' which is marginal on top 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 description opens with a specific verb and resource ('Summarize the salaries employers published in open Quera jobs'), adds the grouping key (seniority level) and the unit (Toman per month). It also distinguishes itself from the qr_jobs sibling by pointing to it as the raw-postings source.

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 trigger phrase ('how much does a junior Python developer earn') plus an explicit caveat that only a minority of postings list salaries, framing the output as a rough sample. The final sentence routes the agent to qr_jobs with order='high_salary' when it needs the underlying postings instead of the aggregate.

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