baba News by baba Hebrew

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds two behavioral details: the required API scope and the fallback to English for untranslated fields. These go beyond the annotations and help the agent understand permissions and output 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?

Two short sentences with no filler. The main purpose is front-loaded, and the scope requirement and fallback behavior are stated efficiently. Every word 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?

For a read-only list tool with a well-documented schema and an output schema, the description covers the essential context: purpose, prerequisite, and a key output behavior. Pagination and error handling are already specified in the schema. The only minor gap is not explaining what 'coverage gaps' means in detail, but the title and context make it understandable.

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

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

Schema coverage is 100%, so all six parameters are fully documented in the schema. The description's note about English fallback is already present in the lang parameter description, so it adds no new parameter-level meaning. Baseline 3 is appropriate when the schema carries the parameter 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?

The description states 'Coverage gaps, by camp' which clearly identifies the resource and scope. The tool name 'blindspots_list' reinforces a list operation. It is distinct from siblings like stories_list or search_list because it specifically targets coverage gaps per camp, though it does not explicitly name alternatives.

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 a prerequisite ('Requires the stories API scope') but gives no explicit guidance on when to use this tool versus siblings like stories_list or search_list. The context is implied by the title, but there are no exclusions or 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 mark it read-only and non-destructive; the description adds two useful facts beyond them: the tool requires the 'brief' API scope, and untranslated fields fall back to English. This gives an agent concrete expectations about permissions and localization behavior. No contradiction with annotations.

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

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

The text is short, but the opening 'Today in Brief.' is redundant with the title and adds no operational value. The remaining two sentences are useful, so the definition is not bloated, just minimally under-specified.

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-optional-parameter tool with a rich output schema and safety annotations, the structured data does most of the work. Still, the description never states what object the tool returns or why an agent would choose it, leaving the core purpose to inference. It is adequate but not complete.

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

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

Schema description coverage is 100%: the lang parameter already documents its enum, default, and Hebrew-to-English fallback behavior. The description's fallback sentence restates the schema rather than adding new parameter meaning. A baseline 3 is appropriate when the schema carries the 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 is essentially the title ('Today in Brief.') with no verb or resource. It does not explicitly say that this tool retrieves the daily brief or what a 'brief' contains, so an agent must infer the operation from the name. The only functional statement is about language fallback, not purpose.

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 on when to call this tool versus siblings such as stories_list or trending_list. The scope requirement is an authorization note, not a usage condition. The description leaves the agent to infer that this is the daily-brief retrieval 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?

The description adds that English is the fallback for untranslated fields, a behavioral detail beyond the annotations, and mentions the API scope requirement. Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description does not contradict annotations and provides some extra context, but it omits details about pagination or return structure.

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 extremely concise, using three short statements. It front-loads the purpose and includes only necessary information (scope requirement and language fallback). There is no filler or redundant content, making it efficient.

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 that the schema fully documents parameters and there is an output schema, the description provides the core purpose and a scope requirement. However, it does not elaborate on what entities the feed tracks or how to use the cursor for pagination, though these are likely covered by the schema. It is adequate but not rich, leaving some ambiguity about the exact nature of the feed.

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 covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds no additional parameter semantics; the language fallback mentioned in the description is already stated in the 'lang' parameter description. No extra value is provided beyond 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 identifies the tool as an 'Incremental change feed' and mentions it requires the stories API scope, which ties it to stories and distinguishes it from siblings like stories_list (current state) and stories_get (single item). However, it does not explicitly state the verb (e.g., 'list') or what entity the changes refer to, so it is clear but not fully specific.

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. It does not mention any sibling tools or conditions for selection. The name implies it is for incremental updates, but the description does not instruct the agent to use it for polling changes or syncing, leaving the decision to inference.

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

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

The description adds several behavioral details beyond the annotations: recentCoverage is always null and why, the requirement for the people API scope, and English fallback for untranslated fields. These are useful and not present in the annotations, which already declare readOnlyHint and destructiveHint. The explanation of the null field is particularly informative.

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, with three sentences that front-load the core purpose. The first sentence establishes the main function, and subsequent sentences provide necessary caveats (null field, auth, language). There is no unnecessary repetition or filler, and it is well-structured for quick scanning.

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 presence of an output schema and annotations, the description is fairly complete. It covers the main purpose, an important behavioral caveat (recentCoverage null), auth requirements, and language fallback. It does not cover error scenarios or rate limits, but for a simple get operation with an output schema, these are minor omissions. The description is sufficient 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 schema has 50% coverage: lang has a description, while id does not. The description adds context by indicating that id identifies a person with aliases folded in, and it reinforces the lang behavior by stating English is the fallback. However, it does not significantly expand on parameter formats or constraints beyond the schema, so it only partially compensates for the missing id 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 clearly states that the tool returns one person with all spelling variants folded into them, covering identity and aliases. It distinguishes itself from the sibling people_list by focusing on a single resource, and the verb is implied as 'get' based on the name and context. It is specific and not tautological.

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

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

The description implies usage for retrieving a single person's details, but it does not explicitly state when to use this tool versus alternatives like people_list. It mentions a required API scope as a prerequisite, but no direct guidance on selection criteria. The name and sibling context suggest the intended use, but the description lacks explicit 'when to use' or 'when not to use' statements.

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 the read-only, open-world, non-destructive nature of the tool. The description adds useful behavioral context beyond those annotations: the required API scope and the English-fallback behavior for untranslated fields.

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 short and front-loaded, with the time scope stated first and the auth and fallback details following. The opening sentence largely repeats the title, but the remaining sentences earn their 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?

For a low-complexity, read-only list tool with an output schema, no required parameters, and simple optional parameters, the definition provides just enough context. The main lingering ambiguity is which timestamp defines 'last 24 hours' and the lack of explicit sibling routing.

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 lang parameter is already well documented in the schema with enum, default, and fallback semantics, and the description reinforces it. The limit parameter only gets min/max/default constraints with no semantic explanation, so an agent must infer its purpose from its 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?

The description clearly names the resource (People) and the temporal scope (last 24 hours), and the tool name 'people_list' supplies the listing action. It is clear enough to distinguish from people_get via the get/list naming pattern, though it does not explicitly draw that 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 description conveys the context: a recent-people listing that requires the people API scope. However, it never states when to prefer this over people_get or the other list tools, and it offers no exclusions or 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 readOnlyHint, openWorldHint, and destructiveHint, so the safety profile is covered. The description adds two useful behavioral details beyond that: the required API scope and the language fallback behavior (English for untranslated fields). These enrich the agent's understanding without contradicting the annotations.

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

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

The description is extremely concise: two sentences, front-loaded with the core action, followed by the critical usage requirement and a behavioral note. Every sentence earns its place, and there is no redundancy or 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?

The tool has 8 parameters and many sibling list/search tools, but the description provides minimal high-level context. While the rich schema and existing output schema cover the mechanics, the description omits guidance on when to choose this search tool over other list tools and does not elaborate on the search scope or result types. Adequate but with clear 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 100%, with detailed explanations for every parameter. The description itself adds essentially no parameter-level meaning beyond restating the lang fallback behavior that the schema already documents. Since the schema carries the full weight, a baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Search stories.' This clearly conveys the core action, and the tool name 'search_list' reinforces it. However, it does not explicitly differentiate itself from sibling tools like stories_list, which also deals with stories, leaving the distinction between search and list 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?

The description mentions a prerequisite ('Requires the search API scope') but gives no guidance on when to use this tool versus alternatives such as stories_list, sources_list, or topics_list. There is no mention of exclusions, preferred conditions, or the /search endpoint mentioned in the schema's parameter description.

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 non-destructive, so the description correctly adds extra context: the required sources API scope, the successRate definition (finished runs only, so in-flight crawls aren't failures), and English as fallback for untranslated fields. These enrich the behavioural model beyond the annotations without contradiction.

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, dense paragraph that front-loads the core purpose and then lists specific metrics and caveats. It is efficient, though slightly packed; each sentence adds value, but it could be trimmed for readability without losing content.

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 output schema exists, the description does not need to explain return values. It covers the key behavioural nuance (successRate), auth scope, language fallback, and the distinction from profile data. Missing details like pagination or additional filtering are minor and likely covered by schema or context. Overall, it is sufficiently complete for a read-only metrics 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 50% (only 'days' has a description; 'key' has none). The tool description does not discuss parameters at all, so it fails to compensate for the missing 'key' semantics. The agent gets no added meaning beyond the schema for either parameter.

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 'Measured newsroom behaviour' and immediately clarifies it is about what the newsroom did rather than its profile, explicitly listing the metrics (crawl outcomes, byline, originality, opinion, press-release, filing-lag rates). This clearly distinguishes it from profile-focused siblings like sources_get and sources_list, making the tool's purpose 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?

It contrasts actual behaviour with profile claims, implying use for behavioural data vs. static profile data, which is helpful for selection among siblings. It also gives a critical caveat about successRate being over finished runs only. However, it does not explicitly name alternative tools or state when not to use it, leaving some inference 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?

Annotations already cover read-only and non-destructive behavior. The description adds two useful behavioral facts: the required 'sources API scope' and that English is the fallback for untranslated fields. These go beyond the annotations, but the description omits other relevant behaviors like error handling or output structure, 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?

The description is short and to the point, but it repeats the title ('One newsroom') and packs the scope and fallback details in a compact way. It is not verbose, but the opening sentence adds little new information, so it is not optimally structured or front-loaded.

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 one-parameter tool with an output schema and annotations, the description is still incomplete. It fails to state the core operation clearly, offers no usage guidance, and leaves the parameter undocumented. The scope and language fallback are useful but do not compensate for the missing essentials.

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 sole parameter 'key', and the description does not explain what 'key' refers to. There is no mention that it is the newsroom identifier or any format hint. The agent is left with an undocumented parameter, making correct invocation difficult.

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 says 'One newsroom' which implies fetching a single entity but lacks an explicit verb like 'get' or 'retrieve'. It essentially restates the title and does not clearly differentiate from siblings like sources_list or sources_activity. The purpose is vague and left to inference.

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 given on when to use this tool versus alternatives. It does not mention conditions, prerequisites beyond the scope requirement, or contrasts with sibling tools. The agent cannot decide between this and sources_list without additional context.

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 communicate readOnly, openWorld, and non-destructive behavior. The description adds useful context about the required API scope and the English fallback behavior for untranslated fields, which goes beyond the annotations. However, it does not disclose potential quirks like pagination, sorting, or rate limits, so it provides only partial 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 extremely concise: two sentences, each earning its place. The purpose is front-loaded, the auth requirement is clearly stated, and the localization nuance is included without padding. No redundant phrases or 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?

For a simple list tool with one optional parameter, full schema coverage, a clear output schema, and annotations that cover safety, the description is nearly sufficient. The only missing context is behavior around pagination or result limits, but given the low complexity and available structured data, the description is adequately 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 coverage is 100% and the single optional parameter 'lang' is fully documented in the schema, including its enum values and default. The description merely restates the fallback behavior already in the schema ('English is the fallback for untranslated fields'), adding no new semantic value. Baseline of 3 is appropriate.

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

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

The description clearly states the verb 'List' and resource 'newsrooms', making the tool's basic purpose obvious. It does not explicitly differentiate from siblings like sources_get or sources_activity, but the 'list' vs 'get'/'activity' distinction is implied by the name and title.

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 mentions a prerequisite (requires sources API scope) but provides no guidance on when to use this tool over alternatives such as sources_get, sources_activity, or search_list. There is no mention of filtering, pagination, or use cases, leaving the agent to infer when this list endpoint 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?

Annotations already declare readOnlyHint, openWorldHint, and destructiveHint, so the description adds the stories API scope requirement as extra context. It repeats the language fallback already present in the lang parameter schema and does not disclose error or not-found behavior, keeping this at a mid score.

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: three short sentences front-load the purpose and keep the API-scope prerequisite immediately visible. The first clause is close to title duplication, but there is no padding and each sentence contributes a distinct fact.

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

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

The output schema and annotations cover the return shape and safety profile, while the description adds the auth requirement. Still, the required ckey parameter is left unexplained alert, and there is no guidance for choosing this over sibling tools, so the definition is not fully self-sufficient.

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

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

Schema description coverage is only 50%, with ckey having no description, and the description never explains what ckey represents. The only parameter-related sentence about English fallback duplicates what the lang schema already states, so the required parameter remains 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 names the resource (Story detail) and its content areas (members, timeline, framing), making the object and scope identifiable. It lacks an explicit verb, with 'get' only appearing in the tool name, and it does not differentiate itself from sibling tools like stories_members.

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 a prerequisite ('Requires the stories API scope') and a language-fallback note, which is useful context. However, it never explicitly says when to prefer this tool over stories_members or stories_list; the use case is only implied by the phrase 'Story detail'.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context: the required API scope and the English fallback for untranslated fields. However, it omits pagination behavior and return format, which are partially covered by the schema and output schema. No contradiction with annotations.

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

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

The description is two short sentences with no fluff. The core action is front-loaded, followed by two behavioral notes. It is efficient, though possibly too terse to convey full usage context.

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's complexity (7 parameters, output schema, many siblings), the description is incomplete. It does not explain when to use this tool, how pagination works, or what distinguishes it from other list tools. The output schema covers return values, but usage context 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 every parameter is already well-documented in the schema. The description adds no parameter-specific information beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a clear verb and resource ('List stories'), which is unambiguous. However, it does not differentiate from sibling list tools like threads_list or topics_list, nor from stories_get (single story). The purpose is clear but generic.

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 versus alternatives. It does not mention pagination, filtering use cases, or when to prefer stories_get for a single story. The agent must infer usage from the schema and sibling names.

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 non-obvious behaviors beyond the annotations: filtering by side/lean is based on the source registry rather than the row, causing pages to be shorter than the limit while still returning a cursor. It also states the auth scope requirement and the English fallback for untranslated fields. These add significant context and do not contradict the readOnly/openWorld hints.

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: the first sentence states the core purpose, and subsequent sentences add essential details without redundancy. Every sentence earns its place, covering purpose, pagination, filtering, auth, and language behavior.

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's complexity (6 parameters, filtering, pagination) and the presence of an output schema, the description covers all critical aspects: what it returns, how paging and filtering behave, auth requirements, and language handling. The agent has enough information to call it correctly without needing to inspect the schema for behavioral nuances.

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 83%, and the description adds extra meaning to side/lean (source registry origin) and lang (English fallback), which goes beyond the schema descriptions. The ckey parameter lacks a schema description, but its purpose is clear from the tool context. Overall, the description enriches parameter understanding beyond 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 title and description clearly state the tool returns every article in a cluster with paging. It references the specific endpoint /v1/stories/{ckey} and distinguishes itself as the paged/filterable variant, which differentiates it from siblings like stories_get and stories_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?

The description implies when to use this tool: when you need paged or filtered access to cluster members, as opposed to the non-paged endpoint. It also mentions the required API scope. However, it does not explicitly name alternative tools or state when not to use it, leaving some inference 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?

Annotations already declare readOnlyHint and destructiveHint false, but the description adds valuable behavioral context: the arc is bounded by limit and returned whole rather than paged, instalments are newest first, and English is the fallback for untranslated fields. These are not present in annotations and significantly aid the agent. No contradiction with annotations.

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

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

Three sentences that are concise yet informative. The first sentence is somewhat poetic but the second clarifies the concrete behavior, and the third covers prerequisites and language. The description is appropriately sized, with no 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 an output schema exists (not shown but indicated) and annotations cover safety, the description covers key aspects: what is returned (all instalments, newest first), ordering, paging behavior (whole rather than paged), language fallback, and required scope. It lacks explicit error handling or rate limits, but these are not critical for a read-only getter. It is sufficiently complete for an agent to invoke correctly.

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

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

The input schema describes lang and limit in detail, and id is required but undocumented. The description indirectly references limit ('bounded by limit') and language fallback ('English is the fallback'), adding slight meaning beyond the schema. With 67% schema coverage, the description partially compensates but does not explicitly explain the id parameter's role.

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 indicates the tool retrieves a running story's entire arc (a thread) with all its instalments, newest first, and in the same shape as a story on /v1/stories. This differentiates it from siblings like threads_list (which likely lists threads) and stories_get (single story). The verb 'get' is implied by the name and the description makes the resource and scope explicit, though it is slightly poetic.

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 mentions it returns the whole arc rather than paging, implying a distinction from tools that page, and notes it requires the stories API scope. However, it does not explicitly name an alternative tool or state conditions for when to choose this over others. The guidance is implicit rather than explicit.

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

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

Annotations already mark read-only/open-world/non-destructive; the description adds the auth scope requirement and the language fallback behavior, both useful. No contradiction with annotations.

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

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

Two short sentences, first states purpose, second compresses two non-obvious facts. No filler or redundant restating of schema details.

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 read-only list with full schema documentation and an output schema, the description covers the important prerequisite and a non-obvious localization behavior. An agent has enough to invoke 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 covers 100% of parameters with defaults, ranges and error behavior, so the description's job is minimal. The English fallback sentence largely repeats schema info rather than adding new parameter-level meaning.

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 running stories' rather than all stories. It does not explicitly distinguish itself from siblings like stories_list or threads_get, but the 'running stories' wording gives a clear 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?

Gives a hard prerequisite (stories API scope) and implies the use case of listing running stories, but never says when to prefer this over stories_list or threads_get, nor rules out 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds two useful behavioral details: the API scope requirement and the English fallback for untranslated fields, though 'live volume' remains unexplained.

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 short, but its first sentence is a verbatim repeat of the title and contributes no information. The second sentence is useful but is the only part that earns its place.

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

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

With an output schema present and full parameter coverage, the remaining gap is the tool's core purpose: an agent still cannot infer what topics_list returns or what a 'desk register' means. The description leaves the central question unanswered.

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 days and lang. The description adds no new parameter meaning beyond what the schema says; the English fallback note is essentially a restatement of the lang parameter's own 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 repeats the title verbatim ('The desk register with live volume') without ever stating what the tool lists or what action it performs. It does not mention 'topics' or 'list' and gives no basis for distinguishing topics_list from the many sibling list 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 only practical guidance is the required sources API scope and the language fallback behavior. There is no statement of when to use this tool versus alternatives such as stories_list, search_list, or trending_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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description need not repeat that. It adds useful behavioral context: the required API scope and the English fallback for untranslated fields. These go beyond the annotations and help the agent understand auth and language 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 concise, two short sentences with no redundancy. The main concept is front-loaded, and the additional requirements are stated efficiently. It is appropriately sized for the tool's simplicity.

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 a rich schema (5 params, 100% coverage) and an output schema, the description is minimal but sufficient. It adds auth scope and language fallback, but does not explicitly state the return type (list of trending stories) or the ranking mechanism, though these are implied by the name and schema. It is adequate but leaves some context to inference.

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 five parameters are fully documented in the schema. The description adds no additional meaning about parameters, such as how they interact or typical usage. It meets the baseline for a fully-covered schema but does not enhance parameter understanding.

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 'Stories picking up speed' conveys the concept of trending stories but is metaphorical and does not explicitly state that this tool returns a list of trending stories. It is distinguishable from siblings like stories_list by the 'picking up speed' hint, but the purpose is not stated with a clear verb+resource pattern. The name helps, but the description alone is 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?

No guidance is given on when to use this tool versus alternatives. It mentions a prerequisite (stories API scope) but does not explain when to choose trending_list over stories_list or other siblings. There is no mention of use cases, exclusions, or alternatives.

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