Analytics Legends — SAP AI & Analytics MCP Server

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

Annotations already cover readOnly/idempotent/non-destructive, but the description adds real behavior the agent could not infer: `value: null` is a served bucket meaning the field is unknown, and dropping it would silently under-count the population. This is exactly the kind of non-obvious trait worth disclosing.

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?

Purpose and the search_firms contrast are front-loaded, and the null-bucket caveat is a worthwhile final sentence. The prose is dense with em-dashes and long clauses, so it is slightly heavier than needed, but no sentence is 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 six-parameter aggregation tool with full schema coverage, an output schema, and safety annotations, the description supplies the remaining decision-relevant context (when to use it, how nulls are handled). Nothing needed to call it 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 the baseline is 3, but the description adds legitimate meaning: filters reuse search_firms' vocabulary, `by` has no safe default, and the null bucket semantics affect how filter results should be read. It does not restate the enum values.

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 ('Answer a COUNTING question') and resource ('the published firm directory') and enumerates the five facets counted. It explicitly distinguishes itself from search_firms, so an agent can route without opening either schema.

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

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

Explicitly names the alternative ('Use this instead of paging `search_firms` and tallying rows') and gives the condition that selects this tool (directory holds thousands of orgs; reading all rows costs hundreds of calls). Also notes the filters mirror search_firms' vocabulary.

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 the safe read-only, idempotent, closed-world profile, and the description adds substantially more: pagination is key-gated (free key gives cursor paging, no key = first 10 rows only), `status`/`is_preview` are served but never filtered on and do not coincide, `_meta.tranche_total_row_count` is the only count to quote, and body access requires a Consultant-tier subscriber key. This is real operational context beyond 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?

Front-loaded with the purpose, but the single block runs long and carries pricing detail (€29.90 Consultant Pass vs €39.90 MCP Pass) that is tangential to invoking the tool, plus repeated emphasis on the catalogue-vs-certification point. Information-dense rather than wasteful, but it does not earn every sentence.

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 5-parameter, zero-required search tool with an output schema and rich annotations, nothing an agent needs is missing: filtering, ordering semantics, pagination protocol, auth tier, and the meaning of the served flags are all covered. The return-field list is even summarised despite an output schema existing.

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 carries the parameter mechanics; the description nonetheless adds value by pointing at the live `_meta.available_tracks`/`available_levels` vocabularies as the source of valid facet values and by explaining that `track_id` is deliberately rejected. It stops short of adding syntax the schema lacks, so it sits just above the 3 baseline.

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 (the Academy written-training catalogue) and immediately distinguishes itself from the two siblings that share overlapping vocabulary — `list_sap_modules` (the 40-row product taxonomy) and `get_academy_module` (the module body). An agent can route correctly without opening any schema.

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

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

Explicit when-to-use (search the course catalogue by track/level/free text), explicit when-not (certification questions have no answer here, not a partial one; module bodies belong to `get_academy_module`), and names the sibling to use instead for product normalisation. It even tells the agent to read `_meta.available_tracks`/`available_levels` before assuming a facet value exists.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description still adds substantial non-structured behavior: source_url/application_link are gated at Consultant tier while the row itself is public, citation_url is the quotable canonical page, rate_band is editorially inferred and never the employer's rate, and rate_band is null on every row as of 2026-08-29. It also flags the 2026-08-28 shape change on the promoted leg so an agent does not over-infer nulls.

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 well front-loaded, but the body is a wall of prose with emoji markers, redundant restatements ('read the `_meta` counters on YOUR OWN response' recurs), and long parenthetical asides about measurement dates. Much of the content is legitimate complexity, but the same warning is repeated three or four times and could be cut by half without losing meaning.

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 8-parameter tool with two heterogeneous legs, gated fields, and misleadingly-named rate fields, the description covers nearly everything an agent needs: leg semantics, gating, null behavior, filter side effects, and which _meta counters to cite. Given an output schema exists, some of the response-field detail is redundant rather than additive, which keeps it from a 5.

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 earns the extra point by adding semantics the schema alone would not convey — that lang is a rendering choice rather than a filter, that country now spans both legs, that cursor must be replayed with identical filters, and that remote_mode silently sets aside undeclared rows. The rate-field explanation is valuable but describes response fields rather than parameters.

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 gives a specific verb and resource ('Search every SAP contract and permanent-role posting Analytics Legends publishes') and immediately separates the two legs, which is genuinely useful disambiguation. It does not, however, position itself against any of the 20+ siblings (search_firms, get_day_rate_benchmark, find_partner_candidates), so an agent gets no routing help beyond the resource name itself.

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 strong conditional guidance: read employment_type before treating this as a contract market, do not assume a null field on the promoted leg, read _meta counters on your own response, rate_band is null everywhere, country now applies to both legs. What is missing is when to pick this over a sibling tool (e.g. versus get_day_rate_benchmark for rate questions), so usage guidance is thorough within the tool but not comparative.

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 the safe read-only/idempotent profile, but the description adds real operational context: subscriber API key with Legend-tier prerequisite, cursor pagination semantics, the ordering rule (SAP signal then data completeness), the row contents, and the privacy constraint that no person or e-mail is returned. This is information an agent cannot recover from 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?

Purpose and the key scoping constraint (local_only) are front-loaded, and every clause carries information. It is a dense single block and repeats some schema content (e.g. the local_only default), which keeps it from a 5 but 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?

Despite an output schema existing, the description still covers row shape, ordering, auth prerequisites, and pagination, and it flags the mandatory target market and the competitor-vs-partner distinction. An agent has everything needed to invoke it correctly without opening the schema.

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 goes beyond the field definitions by explaining the intent behind local_only (read from the brand-family key of the SSOT) and clarifying that a missing module link means no declared link rather than incapacity. It adds rationale and ranking semantics rather than merely restating 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?

Specific verb ('Rank') plus a precisely scoped resource ('LOCAL service providers of a target country or region' for partnering, subcontracting, or acquisition). It is clearly distinguishable from sibling searches like search_firms or find_sap_clients because it names the market-entry/partner-selection population and even excludes competitors via local_only.

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 strong contextual guidance: the local_only rationale (a global subsidiary is a competitor, not a partner), the requirement of country or region ('a partner search without a target market is the whole directory'), and points to count_firms_by for the live module vocabulary. It never explicitly states when to prefer a sibling over this tool, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context: paywall/tier gating, the fact that verification status is always served and never silently filtered, and that detection is a positive-only signal. It stops short of describing result shape or paging behavior in detail, but that is covered elsewhere.

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 and dense with useful distinctions, and every sentence carries information. It is on the long side, with a slightly meta aside about where counts live ('never in this text'), but nothing is 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?

A filtered-list tool with an output schema and full annotation coverage; the description supplies the tier gating, detection semantics, and cursor behavior an agent needs, and correctly omits return-value detail that the output schema and `_meta` handle.

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 genuine semantic depth the schema lacks: the meaning of a dropped row under `product` (undetected, not unused) and the location of verification status columns. This goes beyond restating field definitions.

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+resource (search the SAP END-CUSTOMER corpus) and immediately disambiguates from the nearest sibling by naming search_firms as the service-provider corpus. An agent can route correctly without opening any schema.

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

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

Explicitly states who this is for (companies that RUN SAP, not sellers), the access precondition (subscriber API key, Legend tier or above), and the alternative (search_firms). It also names get_sap_client_profile as the source of the uses_* columns, giving a clear sibling handoff.

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 readOnly, idempotent, openWorld, non-destructive, so the safety profile is covered. The description goes well beyond them: the result set is small (a few dozen rows), every row is a secondary source, sample_size is null on most rows, amounts are in each row's own currency, and bdc/joule return 0 rows rather than widening. This is meaningful disclosure about data shape and limits that the 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?

Purpose is front-loaded in the first clause, but the body is bloated with self-justifying digressions — the 'frozen pair stood here until 2026-08-27 … the second half was WRONG (7 of 11)' anecdote and the argument about why no count is written. These do not help an agent select or invoke the tool and crowd out the genuinely useful routing rules.

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 3-optional-parameter, read-only aggregate with an output schema and full annotation coverage, the description supplies the edge-case semantics an agent most needs: empty-result interpretation differs by region, and _meta.available_* must be read before declaring a rate unpublished. It is arguably over-complete, but nothing an agent needs 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% and the schema descriptions are themselves rich (the specialisation field already documents exact matching, the live _meta list, and 0-row behaviour). The description largely repeats that advice rather than adding new syntax or format detail, so the baseline 3 applies; the per-row currency guidance is about output, not parameters.

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 clause states a specific resource and content: a PUBLIC day-rate aggregate giving min/max daily rate by country, specialisation and seniority. It also explicitly distinguishes itself from the sibling instrument (find_opportunities.rate_band, which it does not serve). The signal is clear but has to be excavated from a great deal of surrounding argument.

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 unusually explicit routing rules: when a country × product query returns empty inside a European grid region, say the aggregate holds no row; anywhere else, say no rate is published at any tier. It names the alternative instrument and its European-only coverage. What it lacks is ordinary when-to-call-this guidance relative to siblings like find_opportunities, since the guidance is framed around how to narrate an empty result rather than when to select the 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?

Annotations already establish readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real context: counts are read at query time from the SSOT, an API key at Legend tier or above is required, and GLOBAL is refused. It does not cover rate limits or cost, but the auth and freshness disclosures are substantive.

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

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

It is one dense paragraph packing several distinct facts (brief contents, region taxonomy, day-rate handoff, SSOT freshness, auth tier) with no structural breaks, which makes it slow to scan. Most sentences do carry information, but the whole could be split and front-loaded more aggressively.

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 values need not be described. With that removed from scope, the description covers inputs, region semantics, refusals, data source, auth tier, and the alternative for day rates — everything an agent needs to call it correctly.

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

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

Schema description coverage is 100% and the schema already defines both enums and the home_region bridge semantics, so the baseline is 3. The description adds value beyond the schema by clarifying the six-value geography (EMEA includes the Middle East, AFRICA is standalone, GLOBAL is the country-unknown bucket) and why GLOBAL is invalid as a target.

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 deliverable (a pre-subsidiary-opening brief) and enumerates its sections: providers by kind/country with LOCAL vs multi-region split, SAP end-customers by country/industry, live opportunities, and bridge groups. It explicitly distinguishes itself from the sibling that handles a related need (get_day_rate_benchmark) and from row-level tools by noting counts 'never rows'.

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 when-to-use context (reading a brief before opening a subsidiary in another region) and routes the adjacent need elsewhere: 'Day rates are NOT in this brief: call get_day_rate_benchmark per country.' It also states an explicit exclusion (GLOBAL is refused as a target region) and explains the home_region omitted-vs-set behavior.

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, non-destructive, closed-world), and the description goes well beyond them by explaining what partnerships_declared actually means, warning that 0 indicates 'none recorded here' rather than 'no partners', and clarifying that a sibling link is an inference of shared brand, not a declared org chart. That interpretation guidance is exactly the kind of context annotations cannot supply.

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 correctly — action first, then return-shape caveats — but it is over-stuffed with measurement trivia: precise percentages with comma decimals, multiple re-measurement dates, and the historical '~97 % until the brand-family pass' narrative. The core warning about misreading 0 earns its place; the surrounding statistics are heavier than an agent needs.

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

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

Single required parameter, output schema present, annotations covering read-only/idempotent/closed-world, and the description still adds the interpretation caveats an agent needs to avoid false conclusions (empty partnerships, slug refusal not implying absence). Nothing required to call it 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 slug property description is itself extremely detailed, so the schema does the heavy lifting. The description reinforces the 'verbatim from search_firms.rows[].slug' rule but adds little semantic detail beyond what the schema already states; 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 ('Fetch one organisation from the published directory') scoped by an exact identifier source, and distinguishes itself from siblings by explicitly excluding the paid firm-intelligence profile (get_firm_intel) and search_firms' list output. An agent can route correctly without opening any schema.

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

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

Gives concrete context for use: pull rows[].slug from search_firms verbatim to call this. The exclusion of the paid firm-intelligence profile implicitly points to get_firm_intel, but the description never names that alternative or states the condition under which to prefer it, so the when-not side 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?

Annotations already declare read-only/idempotent/non-destructive, yet the description layers on substantial extra behavior: the auth/tier requirement, the null-on-all-but-a-few fields, the critical sparsity warning (78% null day rate, 85.7% null partner level), the 'null = not researched, never no partner level' interpretation rule, and the signed-URL exclusion for person 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 purpose is front-loaded and much of the content (sparsity warning, tier requirement, field exclusions) earns its place. However the long parenthetical reciting measurement dates and self-referential commentary ('no reader of this sentence was told') is editorial bloat that an agent does not need in order to invoke 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 no explanation, and the description still covers auth tier, field availability, data-gap semantics, pagination via cursor, and the sibling directory boundary. Nothing an agent needs to call it 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%, so every parameter (mode, name, limit, cursor, country, delivers) is already documented in the schema with its declared-only semantics. The description adds only the top-level 'search by name' hint and sparsity framing, which is not parameter-level detail 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?

States a specific verb and resource ('The paid intelligence profile of a services firm') and enumerates the exact fields returned (SAP practice size, partner level, day rate, clients, LinkedIn URL). It also explicitly differentiates itself from the sibling search_firms ('a different, wider population'), so an agent can route without opening either schema.

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

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

Gives concrete usage conditions: requires a Legend-tier subscriber key, search by name, and the alternative public directory is search_firms. It also carves out a hard exclusion (person-shaped fields never served at any tier). It stops short of a crisp 'use this instead of get_firm when...' rule against the closest sibling.

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?

Beyond the read-only annotations, it discloses important boundaries: the four carried node types, eight excluded node types documented in `_meta.excluded_node_types`, consultant data served at no tier, and `_meta.available_edge_types` as the runtime authority. It also explains language fallback behavior and cursor reuse constraints, which are behavioral context not present 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 long but appropriately so for a complex, multi-parameter traversal tool, and it is front-loaded with the core edge-vs-row distinction. Every major sentence appears to carry operational information, including scope boundaries, invocation modes, and dynamic meta fields.

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, 8 parameters, full schema descriptions, annotations, and an output schema, the description is complete enough for correct invocation. It covers purpose, scope, alternatives, edge/node distinction, parameter intent, pagination, language fallback, and dynamic metadata without needing to describe return values already covered by the output schema.

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 substantial meaning: node_id examples and its role in switching rows from nodes to edges, direction being ignored without node_id, query applying to node listings rather than walks, and lang affecting served labels with declared fallback. These details go well beyond the schema's field descriptions.

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?

It states a specific verb and resource — traversing the learning knowledge graph for relations — and explicitly distinguishes this as the only tool on the server that serves edges rather than rows. The scope is narrowed to four node types and the contrast with 'what exists' tools makes the 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 tells the agent exactly when to use it: 'Ask it what connects to what, not what exists,' and contrasts it with sibling node-serving tools. It also explains the two invocation modes clearly — walk via node_id or discover a node id first via node_type and/or query — and notes how edge_type and direction narrow a walk.

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 read-only/idempotent/closed-world, yet the description adds substantial behavior beyond them: keyed pagination with a 10-row free tier and no cursor, cursor invalidation when filters change, and result ordering rules (name-match tiers when `query` is set, quality ranking otherwise). It also resolves a real ambiguity — that `is_client` outranks `client_enterprise` when flag and label disagree — which prevents systematically wrong filtering.

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?

Purpose is front-loaded, but the middle section is bloated: the flag-vs-kind point is restated three ways ('The two are different columns', 'the flag decides', 'read the flag's meaning into the answer and not the label's') and the pagination warning is shouted in caps. The same information could be delivered in roughly half the words without losing meaning.

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 7 optional parameters, an output schema, and full annotation coverage, this description covers everything an agent needs to call it correctly: pagination lifecycle, ordering, filter interaction, and the one semantic trap (flag vs kind) that would otherwise corrupt the answer. Return fields are mentioned but the output schema carries the detail.

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; the description still earns above that by explaining ordering semantics for `query` (word-substring narrowing, name-match-first ordering) and the cursor round-trip contract. The `module` caveat about declared-vs-actual coverage is a genuine interpretive aid, though most of the per-parameter text is duplicated in 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?

States a specific verb (search) and resource (the published Analytics Legends directory of SAP AI & analytics service providers), then enumerates the kinds it covers. It distinguishes itself from data-adjacent siblings by explicitly scoping out SAP end-customer companies, which is exactly the boundary between this tool and find_sap_clients/find_sap_client_profile.

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-NOT ('SAP END-CUSTOMER companies are NOT in this directory') and points to sibling tools for vocabulary discovery (list_firm_kinds, count_firms_by). It does not name the sibling the excluded data actually lives in (find_sap_clients), so the alternative is implied rather than stated.

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.