Analytics Legends — SAP Analytics Intelligence

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, lowering the burden. The description adds valuable behavior beyond those hints: null buckets are real and served rather than hidden, counts reflect the full population, and filters match search_firms exactly. This prevents an agent from misinterpreting missing facets.

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, each earning its place: purpose, usage rationale, and a crucial data-completeness behavior. It is front-loaded with the core action and keeps the details relevant rather than padding.

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 counting tool with a rich input schema and an output schema present, the description covers the essential context: what it counts, how it relates to search_firms, when to prefer it, and how null buckets behave. Nothing critical 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 coverage is 100%, so the schema already documents each parameter well. The description still adds useful relational context: the filters are the same ones search_firms accepts, and counting a filtered slice is as easy as counting the whole. This helps an agent reuse knowledge of a sibling tool.

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: 'Answer a COUNTING question about the published firm directory'. It names the four facets (country, kind, module, SAP signal band) and explicitly contrasts with search_firms, so an agent can tell this tool from its sibling without opening schemas.

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: use this instead of paging through search_firms and tallying rows. It even quantifies why, citing hundreds of calls and megabytes of rows, which makes the trade-off concrete and actionable.

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

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

Beyond the readOnly/idempotent annotations, the description discloses default ordering, pagination behavior via _meta.next_cursor, the live count semantics of tranche_total_row_count, that status and is_preview are served but not filterable, and the measured discrepancy between them. This is substantial behavioral context that the annotations alone do not provide.

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

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

The description is dense and front-loaded with the core search purpose, and the critical disambiguation from list_sap_modules appears early. Some pricing/subscription detail is longer than strictly necessary for invoking this endpoint, but it supports correct routing to get_academy_module.

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 description covers filtering, pagination, ordering, live facet counts, the distinction from sibling tools, access limitations, and count semantics. With a rich output schema present, no essential calling context is missing for an agent to use this 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?

Although schema coverage is 100%, the description adds crucial parameter semantics: query words must all appear as substrings, track accepts slug or English name but deliberately not numeric track_id, and cursor must be passed back with identical filters or it is refused. These details are not inferable from the schema alone.

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 verb ('Search'), a resource (the Academy training catalogue), and the available facets (track, level, free text). It explicitly distinguishes it from list_sap_modules, so an agent can select between the two 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?

The description gives explicit guidance on when to use this tool versus list_sap_modules and get_academy_module, noting the product taxonomy and the subscriber-only module body respectively. It also states clearly that certification questions have no answer here, preventing misuse.

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 safety profile (readOnly, idempotent, non-destructive, closed-world), and the description still adds substantial undisclosed behavior: most radar rows have `source_url: null` and `application_link: "members_only"` (the gated Consultant-tier field), `rate_band` is null on every row with or without a key, cursors are refused when filters change, and the promoted leg's schema shape changed on a dated cutover. That is exactly the kind of context annotations cannot convey.

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

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

The purpose is front-loaded, but the body runs to roughly a thousand words with repeated injunctions ("read the `_meta` on your own response", "never from a figure quoted in this text") and historical churn narratives dated 2026-07-30/08-28/08-29 that do not help an agent decide or invoke. Much of it duplicates the already-verbose parameter descriptions.

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 eight-parameter, two-leg search tool with gated fields and editorial rate bands, the definition covers population, filtering, gating, null-field behavior and pagination thoroughly. With an output schema present, return values need not be explained, so nothing material 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% and the schema itself is already extremely detailed, so the baseline is 3. The description mostly restates schema semantics (lang as a rendering choice, country applying to both legs, remote_mode setting undeclared rows aside) rather than adding parameter-level meaning the schema lacks.

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 opening states a specific verb and resource — searching every SAP contract and permanent-role posting that Analytics Legends publishes publicly — and scopes it to the anonymous visitor population behind /opportunities/. It is clearly distinguishable from siblings like search_firms, get_day_rate_benchmark or search_news, which address different corpora.

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 strong conditional guidance: read `employment_type` before treating this as a contract market, use the argument to filter, expect `rate_band` to be null everywhere, and never quote bands across postings. It does not, however, name a sibling tool as the alternative when this tool is the wrong one, so routing is implied 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?

Although annotations already mark readOnlyHint, idempotentHint, and destructiveHint, the description adds key behavior beyond those flags: the dataset is gated behind a subscriber key/Legend tier; verification status is NEVER silently filtered and appears as columns; product filter drops rows meaning 'not detected' rather than 'does not use'; cursor must be passed with the SAME filter arguments and changing filters refuses the cursor. This gives an agent safety-relevant and semantic behavior that annotations alone wouldn't convey.

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 information-dense but every clause earns its place: the corpus distinction, access tier, verification semantics, product detection semantics, and cursor behavior are all core to correct invocation. There is no fluff or repetition of schema content; it is front-loaded with the end-customer vs firm distinction, which is the most important routing signal.

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 an output schema, six optional params, and a sibling set that includes get_sap_client_profile and search_firms, this description fully disambiguates where and how to use it. It covers access requirements, result semantics, filtering semantics, and pagination constraints. Nothing critical an agent needs to know before calling is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter. The description adds value beyond the schema by explaining the detection semantics of the product enum, the 'never silently filtered' verification columns, and the cursor's same-filter requirement. It does not repeat schema details, so a 4 is appropriate; a 5 would require even more domain-specific parameter nuance beyond what the schema gives.

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 explicitly identifies the corpus (SAP end-customers), contrasts it with the sibling tool search_firms (services firms), and highlights the Legend tier requirement. It also says exactly what 'product' filtering means in terms of detection flags, so an agent can distinguish this tool from get_sap_client_profile and search_firms.

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 first sentence explicitly contrasts with search_firms: end-customers vs firms that sell services. It also explains the paid subscriber key / Legend tier context, tells the agent that verification status is always served and not silently filtered, and describes detection semantics so the agent can decide when to use this versus more detailed profile tools. This is strong when/when-not guidance.

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, and destructiveHint, so the bar is lower. Even so, the description adds substantial behavioral context: authentication requirements, refusal behavior without a key, case-insensitive matching, multilingual content, and a measured response-size justification for not sectioning the module. 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 quite long but each section carries relevant information: purpose, auth, input matching, sibling comparison, and response sizing. It is front-loaded with the core purpose. However, the pricing/tier explanation and graph-walk narrative add more marketing context than strictly necessary for invoking the tool.

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

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

Given the single parameter, existing output schema, and rich annotations, the description is effectively complete. It covers what the tool returns, authentication prerequisites, failure behavior, input variants, and how this tool relates to siblings. An agent has everything needed to select 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?

The schema already fully documents the single id parameter with format examples and provenance, so the baseline is 3. The description adds meaningful extra semantics: both id and slug are accepted case-insensitively, and the id matches the values returned by find_academy_modules and query_knowledge_graph. This goes a bit beyond the schema, justifying a 4.

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: 'Read one Academy training module in full — body, learning objectives and summary, EN, FR and DE'. It also explicitly distinguishes itself from sibling tools by explaining that find_academy_modules only serves the catalogue and that get_study does not return the whole module in one call.

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

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

The description gives clear guidance on when to use this tool versus alternatives: without a subscriber key it refuses and find_academy_modules keeps serving the catalogue; unlike get_study, this endpoint returns the entire module in one call. It also tells the agent where to source the id/slug (from find_academy_modules rows) and how query_knowledge_graph ids relate.

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 significant behavioral context beyond annotations: it explains the level grading history (NULL meaning 'not graded', never 'Beginner'), the fact that content is human-edited, and the exact handling of null values. This goes well beyond the readOnlyHint and idempotentHint annotations, giving the agent critical interpretation guidance. 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 structured with the primary purpose first, followed by important data-quality caveats and exclusion lists. Each sentence adds necessary information, and the length is justified given the complexity of the null handling and the need to clarify what is not returned. It is slightly longer than typical but well-organized.

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 (per signal), the description sufficiently covers what an agent needs: the parameter, the returned fields, the null semantics, and the alternative for missing content. The caveat about subscriber content and the citation_url are crucial for correct usage. No gaps that would prevent a correct 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?

The schema covers 100% of the single parameter (slug) with a description referencing search_concepts. The tool description adds no new meaning beyond what the schema already provides, so a baseline of 3 is appropriate. The description merely restates 'by slug' without elaborating on format or constraints.

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

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

The description clearly states the tool fetches a single concept entry by slug and lists the returned fields (title, category, level, tags, editor's summary). It distinguishes from siblings like get_concept_card and search_concepts by explicitly noting what it does not return (card body, cheat sheet, etc.) and where to find that content, 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?

The description provides explicit guidance on when to use this tool: it returns only public metadata and the editor's summary. It explicitly lists what is NOT returned (subscriber content, why-it-matters, key points) and instructs the agent to follow the citation_url for the full page, effectively directing to alternatives. This is clear exclusions and 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 readOnly/idempotent/non-destructive, and the description adds key behavioral traits: the paywall boundary, the requirement for a Bearer alk_… key at Consultant tier or above, refusal without it, and the fact that the same payload is returned structured in three languages. This goes well beyond annotation-only signal.

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 first sentence is information-dense, but the description then spends several clauses on pricing and pass-equivalence ('€29.90 Consultant Pass', '€39.90/month', 'analyticslegends.ai/pricing/', 'opens the same tier floor here') that do not help an agent invoke the tool. This could be shortened to the auth requirement and the get_concept fallback.

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 tool with full schema coverage and an output schema, the description covers what the card contains, how to obtain a slug, the required authorization, and the fallback behavior. Nothing essential for selecting or calling the tool 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?

The schema already documents the single slug parameter with 100% coverage, including 'verbatim from search_concepts.rows[].slug'. The description repeats the search_concepts source but adds no new parameter-level meaning, so the 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 opens with 'FULL encyclopaedia card for one concept' and enumerates the payload: body, cheat sheet, glossary, pro tip, four analysis tables, and three languages. It also contrasts itself with get_concept, which continues serving public metadata, making the tool's role 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 explicitly states the subscription/auth prerequisite ('Requires a subscriber API key... Consultant tier or above'), the failure mode without it ('this tool refuses'), and the alternative ('get_concept keeps serving public metadata'). It also directs callers to find slugs with search_concepts, which is the correct retrieval path.

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/idempotent/destructive=false, so safety is covered. The description adds real behavioral context beyond that: the aggregate is small and secondary-source only, sample_size is null on most rows, and no paid tier withholds data. The 'frozen pair' digression and the argument about deliberately omitting counts are self-indulgent rather than informative, but they do not contradict 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 first sentence is front-loaded and useful, but the body sprawls across many paragraphs of internal editorializing: a frozen statistic debunked at length, meta-commentary about why counts are not written, and repeated restatements of the same aggregate-vs-panel distinction. A large fraction of the text does not help an agent call the tool.

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

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

With an output schema present, return values need not be explained, and the description instead covers the genuinely tricky parts: cross-tier boundaries, empty-cell semantics, currency-per-row, and _meta fields to consult. It is arguably over-complete on tangential matters but nothing an agent needs to interpret results correctly 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%, and the schema already carries detailed semantics per parameter (country code format, seniority examples, the full specialisation code list and its caveats). The description adds mainly the empty-result interpretation, which is usage guidance rather than parameter meaning. Baseline 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 opening sentence names a specific verb+resource+scope: the public day-rate aggregate with min/max daily rate by country, specialisation and seniority, including exact field names. It also explicitly distinguishes itself from the sibling find_opportunities (which carries rate_band). However, the signal is buried under several paragraphs of editorial argument, so an agent must work to extract the core 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?

Strong conditional guidance: it tells the agent what to report when the tool returns empty (a European cell → say the AGGREGATE holds no row; elsewhere → say no rate is published at any tier), and names find_opportunities.rate_band as the alternative instrument. It stops short of a crisp 'use this when X vs Y' rule and repeats the same distinction multiple times.

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

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

Beyond the annotations (readOnly, idempotent, destructiveHint false), the description adds critical behavioral context: it explains that `partnerships_declared` being 0 means none declared, not that the firm has no partners, and provides measured frequency data. It also notes that a refused slug does not mean the firm is absent, because the published tranche is an editorial subset. This is valuable nuance not captured in 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 efficiently structured: an action sentence, a return-semantics sentence, and an exclusions sentence. It is slightly dense due to the parenthetical measurement detail ('re-measured 2026-08-14... 96,8 %'), but every clause contributes to understanding. It is front-loaded and appropriately sized for a tool with this nuance.

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 complete. It explains the key return field's semantics and the potential misinterpretation, while the schema covers slug handling in depth. No important behavioral or usage aspects are left undocumented for the tool's complexity.

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

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

With schema description coverage at 100%, the baseline is 3. The tool description merely recaps the slug source ('rows[].slug from search_firms') already fully detailed in the schema, adding no new parameter semantics. The schema itself contains extensive guidance on numeric slugs and refusal behavior, but that belongs to the schema, not the tool 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 the action ('Fetch one organisation from the published directory') and the specific resource ('published profile'), using the verb 'Fetch' with a precise scope. It distinguishes from siblings by noting it returns public fields and does not return the paid firm-intelligence profile or contacts, making its 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?

The description implies when to use the tool (when a single firm's published profile is needed) and tells the user to source the slug from search_firms, noting that the slug is taken verbatim. It also states exclusions (no paid profile, contacts, or persons), which hints at alternatives, but it does not explicitly name tools like get_firm_intel or search_firms for those needs.

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 readOnlyHint and idempotentHint annotations already establish safe behavior, and the description adds valuable behavioral detail: null fields mean 'not researched', absent filter results mean 'not declared', and person-shaped fields are never returned at any tier. There is no contradiction between the annotations and the description's behavioral claims.

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 excessively long and contains redundant, confusingly repeated content, especially around data completeness percentages and sparsity warnings. Statements like the repeated 'READ THE SPARSITY BEFORE QUOTING A ROW' block and the garbled 'it read ~39% ... below the truth' passage create noise rather than adding clear value. A tighter description would convey the same essential caveats more effectively.

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, the description covers the essential operational context: access tier, sparse-data semantics, filter behavior, and data-population differences from sibling tools. It does not include the output schema details, but the description still gives enough context for an agent to understand what the endpoint will and will not return.

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?

Every parameter in the schema has a detailed, meaningful description that goes beyond basic type information: name matching is case-insensitive, cursor must be passed back with identical filters, limit has a hard cap of 10, and mode/delivers are explicitly declared-only. These explanations remove ambiguity and give an agent precise instructions for composing valid requests.

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 identifies the tool as a paid intelligence profile for services firms, listing the exact data categories it provides (SAP practice size, partner level, delivery flags, day rate, clients, analytics summary, LinkedIn URL). It also distinguishes this tool from the public directory by stating that search_firms covers a different, wider population, so an agent can confidently choose it for firm-intelligence lookups.

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

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

The description gives concrete usage guidance: requires a Legend-tier API key, search by name, and clarifies that omissions in filter results mean 'not declared' rather than 'cannot deliver'. It also warns against quoting sparse fields and states that person-shaped fields are never served, giving an agent clear guardrails for when to use and when not to use this endpoint.

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, and non-destructive, so the description adds value by disclosing the API key/tier requirement and the source of the id. It does not contradict annotations and provides meaningful operational context beyond the 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 compact sentences. The first states the purpose and content; the second covers auth and id provenance. No filler or repetition of 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?

For a simple single-parameter retrieval tool with an output schema present, the description covers purpose, content, auth, and id provenance. It is sufficiently complete to guide correct invocation without needing to explain return values.

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 already covers the only parameter with 100% coverage. The description adds extra semantic value by explicitly stating that `id` comes verbatim from find_sap_clients.rows[].id, reinforcing correctness of parameter use beyond the schema's brief label.

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 specifies a singular, concrete resource: the full profile of one SAP end-customer with listed content domains (SAP footprint, analytics, identity, evidence). It clearly distinguishes from the sibling find_sap_clients by referencing a specific id from that 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?

States the prerequisite (subscriber API key, Legend tier) and tells the agent that the id should come from find_sap_clients.rows[].id, implying the natural workflow: first list, then get detail. It does not explicitly mention when not to use alternatives, but the referential guidance provides sufficient usage direction.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses significant behavioral traits: a subscriber API key and Consultant tier requirement, the 256 KiB response ceiling, the structure-first behavior, case-insensitive section matching, and inclusion of the introduction. This is rich context useful for an agent.

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

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

Every sentence earns its place: purpose, auth constraint, size limitation, usage mechanism, and pointer to list_studies. The description is front-loaded with the core action and then methodically explains the chunked reading approach without redundancy. Length is justified by the tool's complexity.

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 (auth tier, size limit, section-based reading) and the presence of an output schema, the description fully covers how to invoke it correctly: what to pass, what to expect, and where to get inputs. No critical usage aspect 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 coverage is 100%, so baseline is 3. The description adds value by noting that `section` matching is case-insensitive and that omitting `section` returns not just the section list but also the introduction. It also clarifies that `slug` is verbatim from list_studies, reinforcing schema hints.

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+resource: 'Read one Analytics Legends study BODY — the paid text behind list_studies' metadata.' This clearly distinguishes it from sibling list_studies and other get_* tools by focusing on the full text body, not metadata or other entity types.

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

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

It explicitly tells when to use this tool vs list_studies: 'Find slugs and languages with list_studies.' It also provides a full usage pattern: call without `section` for the section list and introduction, then pass a section heading for one section. No exclusions are needed because the alternative is named.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful behavioral detail: the counts are 'live', indicating freshness and that the data reflects the current state, which is not conveyed by annotations or 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 two sentences, front-loaded with the core function and then a practical usage hint. Every word earns its place, with 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?

Given the simple parameterless signature, rich annotations, and presence of an output schema, the description provides sufficient context for an agent to understand the tool's role and when to invoke it. It adds domain context (published directory, live counts) and usage guidance, making it complete for this tool's complexity.

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

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

There are no parameters, so the description carries no parameter burden. The baseline for zero parameters is 4, and though the description doesn't add parameter-specific meaning, it explains the output grouping by organization kind, which helps set expectations for the result.

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

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

The description clearly states the tool provides a breakdown of the published firm directory by organization kind, with live counts. It distinguishes itself from sibling tools like search_firms by focusing on population-level aggregation rather than individual firm lookup, and explicitly frames it as a precursor to searching.

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

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

The description explicitly says to use this tool before search_firms, providing clear context and a naming the alternative. It lacks explicit 'when not to use' exclusions, but the guidance to use it as a preliminary step is direct and helpful.

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 read-only, non-destructive, and idempotent behavior, so the description does not need to re-cover those. It does add meaningful semantics: signup_url is verified on assessed_at, and a platform absent here is not proof of refusal—it is merely unassessed or unpublished. These boundary details would be hard to infer from the schema alone.

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 main purpose is front-loaded, and every sentence carries signal: what the list contains, which question it answers, how it relates to search_firms, and how URL verification/absence should be interpreted. There is no filler or redundancy with 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?

The description is complete for this read-only list tool: it clarifies scope, a reliable sibling relationship, verification meaning of the returned URL, and absence semantics. With four optional parameters all documented in the schema and read-only annotations present, nothing critical is missing for correct invocation.

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 every parameter already has a focused description including cursor rules, country format, and platform_type behavior. The tool description adds little parameter-level meaning beyond clarifying that the tool applies a platform-type filter, so the appropriate baseline is 3.

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 verb (list) and resource (freelance platforms where a consultant can create a profile) and gives concrete examples of the included platform kinds. It also clearly distinguishes itself from search_firms by stating this is a narrower subset that adds platform fields, so an agent can tell it apart from sibling tools.

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

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

The description explicitly positions this tool as the one answering 'where do I register?' and names search_firms as the broader alternative, clarifying that this tool never returns a wider population. That gives an agent a direct routing decision: use this when platform signup fields are the goal, and search_firms for the broader directory.

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 safety profile (readOnlyHint, idempotentHint, destructiveHint=false, closed-world), so the bar is lower. The description still adds useful content semantics — bilingual EN/FR labels organised by category and the canonical code set — that the annotations do not convey.

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, front-loaded with what the resource is before explaining why to call it. No filler text; 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?

An output schema exists, so return-value detail is not required, and the parameters are self-documenting. Purpose and use case are covered; the only minor omission is any note about pagination behaviour across pages, which the cursor description largely handles.

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 limit, query and cursor are fully documented in the schema itself, including the substring-per-word matching rule and cursor reuse constraints. The description adds no additional parameter meaning, 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 ('canonical SAP module/product taxonomy') and specifies what it contains ('codes and EN/FR labels by category'), which is more precise than the name alone. It also positions itself relative to the other tools by noting these are 'the codes the other tools filter on', so an agent can tell it apart from look-alikes such as list_firm_kinds and list_freelance_platforms.

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 when-to-use with concrete examples ('SAC', 'Analytics Cloud', 'Datasphere') and the goal of normalising loose wording onto filter codes. There is no when-not guidance or named alternative tool, which keeps it short of a 5.

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

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

The description discloses read-only behavior, the one-row-per-language-edition semantics, the `_meta` fields, and the outcome for invalid language codes (0 rows). These details go beyond the annotations and do not contradict `readOnlyHint`, `idempotentHint`, or `destructiveHint`.

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

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

The description is dense and front-loaded with the purpose, but it repeats the language-edition rule twice ('ONE ROW IS ONE LANGUAGE EDITION' and later 'each row carries its editions list'). This minor redundancy prevents a perfect score.

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

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

Given the presence of an output schema, the description appropriately omits return-value details but includes essential operational context: metadata-only nature, pagination, `_meta` fields, and the relationship to `get_study`. It is complete for the intended use.

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 descriptions fully cover all four parameters, so the baseline is 3. The description adds value by reinforcing the meaning of `lang` (one row per language) and the cursor's dependency on unchanged filters, giving extra context 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 clearly states the tool's function: listing deep-research studies with metadata fields (edition, as-of date, audience, word count, URL). It explicitly contrasts with `get_study` for study bodies, making its scope distinct from sibling 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?

It plainly says 'METADATA ONLY,' directs to `get_study` for bodies, and explains the use case ('tell a reader that a study exists and where to read it'). It also covers pagination, language-edition behavior, and filter constraints, leaving no ambiguity about when and how to use it.

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

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

Annotations already declare read-only/idempotent/non-destructive behavior, and the description adds substantial context beyond them: the graph projection can change and is recomputed per call, `_meta.available_edge_types` is authoritative, missing node types are documented rather than silent, language fallback is declared, and cursors are refused when filters change. It even gives a historical example of why the dynamic edge list must be trusted.

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 content is front-loaded and nearly every sentence carries information, but the prose is dense and rhetorically heavy (all-caps emphasis, multiple parentheticals, repeated meta-field warnings). It is appropriately sized for the 8-parameter complexity, though a modest trim would improve readability without losing substance.

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

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

For a complex tool with 8 optional parameters and an output schema, the description covers scope, edge types, pagination cursor semantics, language fallback, node listing vs walking, and meta fields. There is no gap that would prevent an agent from selecting and invoking 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%, but the description adds meaning the schema alone lacks: node_id switches the response from nodes to that node's edges, direction is ignored without node_id, query targets the served label and follows lang, and edge_type is a hint rather than authoritative. Parameter descriptions also give realistic id examples and behavioral edge cases.

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: it traverses relations/edges among Academy teaching objects, distinguishes itself as the only edge-serving tool on the server, and names the four node types it carries. The contrast 'Ask it what connects to what, not what exists' cleanly separates it from row-serving siblings.

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 tells when to use it ('Ask it what connects to what, not what exists'), states it is the only edge tool while sibling tools serve rows, and documents the scope boundaries with excluded node types. It also gives concrete invocation patterns (node_id for a walk; node_type/query to find a node id first), so an agent need not infer when it applies.

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 safety profile (readOnly, idempotent, non-destructive), and the description layers on genuinely non-obvious behavior: level is now graded on every active row, a null means 'not graded' and never 'Beginner', and the body/why-it-matters content is tier-gated or served elsewhere. This is behavioral context an agent cannot infer from annotations or 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?

Front-loads what it returns, then constraint caveats, then sibling alternatives. Mostly efficient, but the parenthetical backstory (CHECK constraint, '108 of 330 were blank') is heavier than needed to convey that null means 'not graded'.

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, the description needn't explain return shape, yet it still covers pagination semantics, tier gating, the null-level edge case, and where the non-served fields live. Nothing an agent needs to invoke this correctly 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 coverage is 100%, so baseline is 3, but the description adds real semantic value on top: cursor must be replayed with identical filters or it is refused, null cursor means last page, and category values are long human labels discovered from _meta.available_categories rather than guessed. The category 'read the envelope, not the prose' guidance materially improves invocation.

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

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

States a specific verb (Search) and resource (SAP AI & analytics concept encyclopaedia / vocabulary of the stack), and explicitly enumerates the returned fields (slug, title, category, level, tags, editor's summary). It distinguishes itself from siblings by noting these are 'the same fields get_concept returns for ONE slug' and that the card body lives in get_concept_card.

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 routing: use this for multi-record search, get_concept for one slug, get_concept_card for the Consultant-tier body, and follow citation_url for why-it-matters/key points. It also names what this endpoint explicitly does NOT serve, which prevents wrong-tool selection.

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 safety profile (readOnly/idempotent/non-destructive), yet the description adds substantial operationally relevant behavior beyond them: full pagination via _meta.next_cursor, cursor refusal when filters change, name-match ordering tiers when `query` is set, and quality ranking otherwise. The flag-vs-kind-code precedence rule for `is_client` is an unusual and genuinely important disclosure.

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 purpose and scope, then pagination and ordering; every sentence carries information. The flag-versus-kind digression is the longest stretch and slightly repetitive ('the two are different columns', 'read the flag's meaning... not the label's'), which keeps it just short of fully tight.

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

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

An output schema exists, so return fields need not be spelled out, and the description still covers the essentials an agent needs: inclusion/exclusion boundary, pagination loop, ordering rules, and filter vocabulary sources. Nothing material is missing for a 6-param, optional-only search 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 100%, so every parameter is already documented in the schema, including the cursor, module, kind and query semantics. The description largely restates those (module absence, cursor reuse) and only the query ordering tiers add meaning beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 published Analytics Legends directory of SAP AI & analytics service providers') and enumerates the entity kinds it covers. It also carves out the boundary against the end-customer dataset, so an agent can distinguish it from find_sap_clients/get_sap_client_profile without opening another 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 clear usage context: what is included, what is excluded (SAP end-customers live in a separate paid dataset), and routes the agent to count_firms_by for live module vocabulary and list_firm_kinds for kinds. It stops short of naming the sibling tool that serves the excluded end-customers, leaving that 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?

Adds substantial context beyond the readOnly/idempotent annotations: the corpus is ~84% general enterprise-AI trade press with no SAP content, unfiltered calls return mostly non-SAP items, and every row comes back citation_scope "section_hub" with an index citation_url while the true article page is source_url. These are exactly the behavioral traits annotations cannot convey.

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 corpus description, but the citation guidance is stated twice ("cite both ... prefer source_url" and again "The citable address for one article is its source_url ... Do not present the hub as the article's page"), which inflates length. Most sentences carry distinct warnings, but the redundancy and overall length keep it from being tight.

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 100% schema coverage, the description still covers the non-obvious gaps: corpus composition, filtering necessity, citation semantics, and cursor reuse. An agent has everything needed to call the tool correctly and interpret results honestly.

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 is 3, but the description adds real meaning: it explains why the category vocabulary is not written out (read _meta.available_categories) and warns that 'SAC' is structurally noisy due to acronym collisions, with a workaround (pair with query:'analytics cloud'). It also justifies why published_since/until matter for match_count correctness.

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?

Opens with a specific verb+resource ("Search the Analytics Legends market-news corpus") and immediately scopes it (SAP AI & analytics topics, not an all-SAP corpus). An agent knows exactly what this tool returns versus siblings like search_firms or search_concepts, which are entity searches rather than news retrieval.

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

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

Gives explicit when-to and when-not-to guidance: "pass `query` or `category` when the question is about SAP, and never present an unfiltered page as 'the SAP AI & analytics news'." It also states the correct pattern for cursors (pass back with the SAME filters) and for period questions (use published_since/until so match_count is quotable), and prescribes citation behavior.

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