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 a safe read-only, idempotent, closed-world operation and the description does not contradict them. Beyond that it discloses genuinely non-obvious behaviour: curriculum ordering when `query` is omitted, `status`/`is_preview` being served rather than filtered (with measured counts showing they diverge), and that pagination requires a key. The heavy commercial framing about the €29.90 pass dilutes this slightly but the behavioural content is substantial.

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?

Core distinction and pagination rules are front-loaded, but the block is long and crowded with ALL-CAPS warnings, pricing tiers and dated measurement asides that don't help an agent invoke the tool. Several sentences could be cut without losing invocation-relevant 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, yet the description still summarises returned fields and, more importantly, covers pagination, key requirements, ordering defaults and facet discovery — the aspects an agent must know to call it correctly. Nothing operationally necessary appears missing for a five-parameter catalogue search.

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, but the description adds meaning beyond it: omitting `query` yields curriculum order rather than an arbitrary listing, and the agent is told to consult `_meta.available_tracks`/`_meta.available_levels` before assuming a facet exists — compensating for the zero enums. Some of the track slug/name and cursor rules merely restate the schema.

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

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

The description opens with a specific verb and resource — 'Search the Analytics Legends Academy ... by track, level and free text' — and enumerates the subject domains covered. It then explicitly contrasts itself with `list_sap_modules`, so an agent can distinguish the course catalogue from the product taxonomy 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?

It gives explicit routing rules: use `list_sap_modules` for the 40-row product taxonomy, `get_academy_module` for module bodies, and this tool for catalogue entries. It also states exclusions ('no certification data at any tier') and pagination conditions ('without a key, first 10 rows only'), leaving little to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real behavioral context: at most three rows, the status source (SAP announcement registry), the caution that 'a date is a plan, not a commitment', and the meaning of an empty result. Enumerating the returned fields overlaps the output schema somewhat, but the plan-vs-commitment caveat is information no structured field carries.

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 trigger condition is front-loaded and the fallback guidance is placed at the end where it belongs. The middle enumerations (twelve challenges, returned columns) are dense and border on schema duplication, but they earn their place by letting the agent judge in-scope vs out-of-scope questions without a second call.

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 search tool with a full output schema, the description covers the trigger, the domain scope, the ranking model, the status provenance, the empty-set behavior and the redirect targets. Nothing material an agent needs to decide whether and how to call it 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 question, lang and audience, including the enums and the 'full sentences match best' hint. The description reinforces the EN/FR/DE matching scope, which ties to lang, but says nothing about the audience enum or that it only reorders already-matched challenges — that nuance lives only in the schema. 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?

A specific verb and resource: it matches a natural-language question to twelve named, ranked challenges, and enumerates them (agents in production, Joule value, the BW cliff, EU compliance, etc.). It explicitly contrasts itself with term lookup ('rather than a term'), which separates it from search_concepts and get_concept_card among the 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?

'Start here when someone asks about an SAP AI & analytics PROBLEM rather than a term' gives an explicit entry condition and an exclusion. The empty-result case is handled with concrete alternatives: search_concepts, find_academy_modules, get_day_rate_benchmark, so the agent knows where to route a miss.

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 safety, yet the description adds genuinely non-obvious behavior: source_url is null and application_link reads "members_only" on most rows (gating a field, not a row), rate_band is null on every row because the radar file stopped carrying it, and rate_basis semantics for panel_inferred bands. It also warns that _meta counters must be read at query time rather than trusting figures in the text — high-value disclosure beyond structured data.

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 body sprawls into dated measurements, change-log narration ("THIS LEG CHANGED SHAPE ON 2026-08-28"), and self-referential instructions about what not to quote from this very text. Several sentences instruct the agent about phrasing rather than describing the tool, which is padding that makes the actionable content harder to extract.

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 explained, and the description nonetheless documents the key _meta counters an agent must consult. Complete for calling correctly, though the sheer volume of volatile detail (specific counts, dates) risks going stale and misdirecting an agent that trusts the prose over its own response.

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

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

Schema description coverage is 100% and the enum/parameter descriptions in the schema are themselves extensive, so the description body largely restates parameter semantics rather than adding to them. Baseline 3 applies; the marginal additions (leg-level null assumptions for country and employment_type) are already present in the parameter 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?

The opening states a specific verb and resource (search SAP contract and permanent-role postings) and explicitly separates the two legs being merged (PROMOTED feed vs SITE RADAR). The core purpose is unambiguous but is buried under several paragraphs of caveats and dated change history, so an agent gets the what-it-does only after wading through the how-it-behaves.

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 conditional guidance: read employment_type before treating this as a contract market, combine eligibility with remote_mode="remote" for the contractor abroad, and note that unfiltered pages answer freelance questions with salaried jobs. It does not say when to use this tool instead of the sibling tools (e.g., get_day_rate_benchmark, search_firms), so sibling routing is left implicit.

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?

Well beyond the annotations (which already establish a safe, idempotent read), the description discloses access prerequisites ('Requires the API key of an MCP Pass or Firm account — the Consultant and Legend web plans do not include MCP access'), the return row shape, cursor pagination, and an explicit privacy boundary ('No person, no e-mail'). These are the operational facts an agent needs before calling.

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?

Material is front-loaded: population, then the local_only rationale, then filters, output, ordering, constraints, auth. Some phrasing is dense and parenthetical (e.g. 'read from the brand-family key of the SSOT'), slightly taxing on first read, but every sentence carries distinct information.

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

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

For a 7-parameter, cursor-paginated read tool with an output schema and rich annotations, nothing an agent needs is missing: target-market requirement, filter semantics, ordering, pagination, auth, and what the rows contain. Sibling tools and an output schema cover the rest.

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 semantics: the country/region gating that the schema does not enforce (zero required parameters), the cursor's 'same filter arguments' contract, and the ranking order by SAP signal then completeness. Some repetition of the schema's declared-module and sister-country wording keeps it from a 5.

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 and a precisely bounded population: 'Rank the LOCAL service providers of a target country or region — the firms a practice partners with, subcontracts to, or acquires to enter a market.' The local_only contrast ('a subsidiary of a global group is a competitor, not a partner') makes it unmistakable against broader firm-search siblings such as search_firms or find_sap_clients.

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 about the mandatory context — '`country` or `region` is required: a partner search without a target market is the whole directory' — and about the local_only toggle's intended meaning. It even routes to count_firms_by for the module vocabulary. It stops short of naming a specific sibling it should be preferred over, so it is clear context rather than full alternative routing.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), but the description adds substantial context they cannot: paid-tier auth requirement, the 2026-07-08 lock date, that verification status is served as columns rather than silently filtered, and that per-call counts live in _meta. The product-detection caveat (a dropped row means 'not detected', never 'does not use it') is exactly the kind of behavioral nuance an agent would otherwise misreport.

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 core differentiator (end-customers vs. firms) and dense throughout, with no filler sentences. A few editorial asides ("never in this text", the exact lock date) are slightly verbose but each still carries routing or trust 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?

With an output schema present, return shape and pagination need not be described, and annotations cover safety. The description fills the remaining gaps an agent actually needs: access tier, verification-status handling, and the asymmetry of product detection. 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 coverage is 100%, so this is already baseline 3; the description earns extra by explaining that `product` filters on positive detection flags only, that a dropped row means 'not detected by our detection pass', and that the flags correspond to uses_* columns served elsewhere. Query/cursor/country semantics stay with the schema, which handles them well.

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 SAP END-CUSTOMER corpus") and immediately disambiguates the exact noun that could confuse an agent: the companies that RUN SAP, not firms that sell services. It names the sibling it is not (search_firms) and the detail tool it complements (get_sap_client_profile), so it is distinguishable 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 routes firm/vendor lookups to search_firms and states the access precondition (API key of an MCP Pass or Firm account, paid Legend+ dataset). It stops short of stating when to prefer get_sap_client_profile over this list tool, or when not to search at all (e.g. tiny result sets vs. bulk export), so it is strong but not complete routing 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?

Beyond the readOnly/idempotent annotations, it discloses the auth scheme (Bearer alk_…), the refusal behavior without a valid pass key, the entitlement split between web plans and MCP access, and the response-ceiling fallback where English is served alone with a `filters.lang` marker for oversized modules like M001. These are operational facts an agent cannot infer from structured 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 critical facts (what is read, key requirement, id/slug, lang fallback) are front-loaded, but the prose is padded with marketing and pricing asides ('the written course corpus the Consultant web plan sells', €29.90/month, 'so a graph walk now ENDS somewhere'). Several clauses could be trimmed without losing callable information.

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

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

For a two-parameter read tool with an output schema and full annotation coverage, nothing needed to call it correctly is missing: entitlement rules, auth header, id provenance, language behavior and the oversized-response fallback are all covered.

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 nevertheless adds value by stating that `id` accepts an id or slug matched case-insensitively and where those values come from (`find_academy_modules.rows[]`, graph `module:M001` nodes). It also explains the `lang` omission behavior and the ceiling fallback that the schema mentions only briefly.

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 and resource — 'Read one Academy training module in full' — and enumerates what is returned (body, learning objectives, summary, EN/FR/DE). It is clearly distinguished from the sibling 'find_academy_modules', which is named as the catalogue-listing counterpart.

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

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

Explicitly states when this tool is needed versus the alternatives: free-account users get only the showcase modules via `find_academy_modules`, while the full paid tranche requires an MCP Pass or Firm Pass key on this endpoint. It also names the condition under which a graph walk terminates here (`query_knowledge_graph` returns `module:M001` ids).

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?

Adds substantial behavior beyond the read-only, idempotent annotations: paid access gating, required Bearer key, refusal behavior, and the exact premium content returned in EN/FR/DE. The annotations already cover safety, and the description adds the access and content context an agent needs.

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 important content is front-loaded, but the description is a long run-on sentence followed by repeated access-plan wording. The Consultant/Legend exclusion is stated twice, and the pricing URL plus lengthy contents list make it more verbose than necessary.

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

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

Given the output schema exists, the description does not need to explain return values and instead covers the critical access, content, and alternative-tool context. An agent has enough information to decide whether to call it and what prerequisites apply.

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

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

Schema coverage is 100% and the single slug parameter is already documented as coming verbatim from search_concepts.rows[].slug. The description only repeats the search_concepts pointer, so it adds little semantic value 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: retrieves the FULL encyclopaedia card for one concept, and enumerates the included sections and languages. It clearly distinguishes this from get_concept by noting that get_concept serves public metadata while this tool opens the paid tranche.

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 explains when this tool is usable: only with an MCP Pass or Firm Pass API key, and it refuses without one. It names alternatives and prerequisites: use search_concepts to find slugs, and get_concept continues serving public metadata when access is missing.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description genuinely adds beyond that: the dataset is small (a few dozen rows), every row is a secondary source, `sample_size` is often null, each amount is in the row's own `currency`, and `_meta.available_*` is recomputed per call. Offset against this, the paragraph about a 'frozen pair' that stood until 2026-08-27 is changelog noise that consumes attention without informing a call.

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 text runs to roughly 500 words for a three-parameter read tool and includes internal meta-commentary (the stale '11 rows on 2026-08-09 … sample_size null on 8 of them' correction, 'NO COUNT IS WRITTEN HERE ON PURPOSE') that does not help an agent invoke the tool. Several sentences repeat the same point about the aggregate not being a paid tier.

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-field explanations are unnecessary, and the description still covers what an agent needs to interpret results: per-row currency, confidence, source date, empty-result meaning, and the coverage boundary against the subscriber band. It is more than complete; the remaining deficiency is editorial discipline, not missing information.

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 all three optional parameters, making 3 the baseline. The description reinforces empty-result semantics and warns that codes are unevenly spread across countries, but that guidance is already largely present in the `specialisation` schema description, so it adds little net meaning.

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

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

The opening sentence gives a specific verb+resource: a public day-rate aggregate returning min/max daily rate by country, specialisation and seniority, with named fields. It also explicitly distinguishes itself from the sibling/instrument it is not (`find_opportunities.rate_band` on live postings), so an agent can route between them 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?

It names the alternatives and the conditions that select them: community aggregates (v_community_rate_aggregates, v_rate_index) publish nothing yet, and the subscriber rate_band exists only on European radar postings. It even prescribes behaviour when results are empty (say the aggregate holds no row in European regions; say no rate exists at any tier elsewhere). The one gap is that the 'use this tool when a user asks about day rates' framing 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context on top: counts are read at query time from the SSOT, Legend figures are counts and never rows, GLOBAL is rejected rather than silently empty, and authentication tier requirements are stated. Nothing about the call's behavior is left for the agent to infer.

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 core purpose in the opening clause, and every sentence carries real information (region semantics, exclusions, auth, corpus provenance). It is dense and parenthetical-heavy, and the day-rate digression is longer than strictly necessary, 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 two-parameter read-only aggregate tool with an output schema, the description supplies everything the agent needs: what each section contains, how regions are defined, the prerequisite credentials, and which adjacent question requires a different tool. The output schema handles return shape, so no gap remains.

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 already documents home_region omission behavior, so this is mostly reinforcement. However the description adds genuine semantics beyond the schema: the six-value geography definitions (EMEA spans Europe AND the Middle East, AFRICA stands alone, GLOBAL is the country-unknown bucket) and the fact that GLOBAL is refused as a target, which the enum alone cannot convey.

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 concrete verb and resource ('one-call brief') and then enumerates the four payloads it returns: providers by kind/country with LOCAL vs multi-region-group split, SAP end-customers by country and industry, live opportunities by country, and bridge groups. It explicitly carves out what it does NOT return (day rates) and names the sibling that does, so an agent can separate it from get_day_rate_benchmark 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?

Names the decision context precisely ('the brief a services practice reads before opening a subsidiary in another region'), states the explicit exclusion and routes to the alternative (get_day_rate_benchmark per country, with its coverage caveat), and spells out the access prerequisite (MCP Pass or Firm account; Consultant and Legend web plans excluded). Both when-to-use and when-not-to-use are covered.

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?

Beyond the readOnly/idempotent annotations, the description discloses things an agent cannot get elsewhere: the paid-account gate (Consultant and Legend web plans are excluded), the hard exclusion of all person-shaped fields at every tier, the LinkedIn URL coverage figure, and the critical null-vs-false distinction for typical_day_rate_eur and sap_partner_level. The weak spot is the embedded editorial aside about a past measurement error, which reads as a correction to a human reader rather than information the calling agent can act on.

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 core content is a single run-on paragraph whose most actionable warnings (null rates on headline fields, auth tier, person-field exclusion) are buried inside em-dash interjections and a lengthy parenthetical about re-measured LinkedIn coverage. The aside explaining that a prior figure was "a third of the corpus below the truth" and that "no reader of this sentence was told" is self-referential noise for an agent and pushes the operational guidance to the middle of the text.

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-format detail is not required, and the description covers the remaining agent-critical facts: auth requirements, the destructive-to-assume null semantics, the person-data exclusion, and the sibling boundary against search_firms. What keeps it short of complete is the absence of any distinction from get_firm despite near-identical naming, and the lack of a stated default behavior when name is omitted.

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 enum/filter semantics (declared-only reading of `delivers` and `mode`, cursor reuse rules, the cap of 10) are all documented in the schema itself. The description adds only the phrase "Search by name" and a general sparsity warning; it contributes essentially nothing about `country`, `limit`, or `mode` that the schema does not already say. Baseline 3 applies.

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

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

The first sentence names the resource concretely (a paid intelligence profile of a services firm) and enumerates the fields it carries, so an agent knows it returns a wide firm record rather than a list of names. It explicitly distinguishes itself from search_firms (public directory, wider population). It does not, however, distinguish itself from sibling get_firm or get_sap_client_profile, which leaves a real ambiguity unresolved.

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?

"Search by name" plus the tier/auth constraint implies the usage context, and the search_firms exclusion is genuinely useful routing. Missing is any statement of when an agent should prefer this over get_firm, get_sap_client_profile, or find_sap_clients, and no guidance on using the filter-only path (omitting name to browse by completeness). Usage is implied rather than prescribed.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real value beyond that with the API-key/tier gating (MCP Pass or Firm account required, Consultant/Legend excluded), which an agent needs before attempting the call. Return shape is not described, but an output schema exists.

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 tight sentences, front-loaded with what the profile contains, then the auth gate, then the id provenance. The id provenance sentence duplicates the schema, which is a minor redundancy, but nothing else is wasted.

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 rightly omits return values, and it covers the two things an agent actually needs: how to obtain the id and what auth tier is required. Error or not-found behavior is the only notable omission for a single-resource fetch.

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

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

Schema coverage is 100% and the schema already states 'Profile id, verbatim from find_sap_clients.rows[].id.' The description repeats that same provenance sentence almost verbatim, so it adds no meaning beyond the structured field. Baseline 3 applies when the schema does the work.

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

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

It names a specific verb-and-resource pairing: the full profile of ONE SAP end-customer, and enumerates what the profile contains (footprint, modules, analytics solutions, identity/evidence). The word 'one' plus the pointer to find_sap_clients.rows[].id makes it clearly distinct from the sibling list/search tool.

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

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

It gives a clear prerequisite chain — get the id from find_sap_clients, then call this — plus an explicit auth exclusion (Consultant and Legend web plans lack MCP access). It stops short of an explicit 'use find_sap_clients instead when you need to search rather than fetch a known id' statement, so there is a small inference left to the agent.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real context beyond that: the auth tier gate, the 256 KiB response ceiling versus 38k-word bodies, and the deliberate structure-first serving pattern. However, with no output schema for the section listing it describes, it leaves open what a no-section response actually contains beyond 'the section list and the introduction' — a 3 rather than a 4 — and much of its added value overlaps what a caller could infer from the auth error, not from documented behavior.

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

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

Four tight sentences, front-loaded with the resource and the distinction from list_studies, then the access prerequisite, then the pagination-by-section mechanic. Every clause carries information an agent needs to call the tool correctly; 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?

The tool has an output schema, so return shapes need no prose, yet the description still covers the two things an agent would otherwise learn only by failing: the account-tier requirement and the oversized-body handling via `section`. For a read-only single-record fetch with three parameters, 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 coverage is 100%, so all three parameters are documented in the schema, including that `section` comes from a previous call's `sections` list and that omitting it returns the list. The description adds only the case-insensitive matching rule, which is useful but narrow. With the schema doing nearly all the work, 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 ('Read one Analytics Legends study BODY') and immediately distinguishes it from the sibling list_studies by calling the body 'the paid text behind list_studies' metadata.' An agent can tell exactly which of the two tools returns full text versus metadata.

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 conditional workflow: call without `section` to get the section list plus introduction, then pass a heading to read one section, and use list_studies to find slugs and languages. It also names the prerequisite (MCP Pass or Firm API key) and excludes the Consultant and Legend web plans, which is genuine when-not-to-use 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 the tool as read-only, idempotent, closed-world and non-destructive, so the safety profile is covered. The description adds useful behavioral context by noting that counts are live and scoped to the published firm directory.

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 tightly written sentences with no wasted language. The resource and output are front-loaded, followed by a clear usage recommendation.

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 the description does not need to explain return values. It is nearly complete for a zero-parameter read-only listing tool, though it leaves the relationship with count_firms_by unaddressed.

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

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

The tool takes zero parameters, so there are no parameter semantics to document. The baseline for a zero-parameter tool is 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 clearly states a specific resource and output: a breakdown of the published firm directory by organisation kind with live row counts per kind. It does not explicitly distinguish itself from the sibling tool count_firms_by, which is the main remaining ambiguity.

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

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

It gives a clear usage context: call this before search_firms to understand the firm population instead of guessing. It does not state when not to use it or how it relates to count_firms_by.

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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantive context beyond them: content is paywalled and requires a pass key, the grain is one row per language edition rather than per study, and the `_meta` counters (`tranche_total_row_count`, `distinct_studies`, `available_languages`, `next_cursor`) are named. That is exactly the non-obvious behavior an agent would otherwise get wrong.

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

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

Front-loaded with the resource and output fields, then scope, then the row-grain caveat, which is the highest-risk misconception. The all-caps warnings and the `_meta` enumeration make it denser than ideal, but nearly every clause carries actionable information rather than 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 4-param, zero-required listing tool with an output schema and full annotation coverage, the description covers access model, row grain, language filtering, and pagination handoff. Nothing an agent needs in order to call it correctly or interpret the counts 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 still adds real meaning by explaining that `lang` collapses the edition-per-row grain into one row per study and that an unknown-but-valid code yields 0 rows, which the schema alone does not convey. It says less about `query` and `cursor` than the schema already does, so it does not fully earn a 5.

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

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

States a specific verb and resource (list deep-research studies) plus exactly what fields each row carries (edition, as-of date, audience, word count, canonical URL), and explicitly separates itself from `get_study`, which serves the bodies. An agent can tell this is the catalog/metadata tool 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 an explicit when-to-use ('tell a reader that a study exists and where to read it') and an explicit when-not/alternative ('study bodies are a paid deliverable, served by `get_study` on this same endpoint with an MCP Pass or Firm Pass key'). It also states the condition that changes the shape of the result ('Pass `lang` to get one row per study').

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, closed-world), yet the description still adds substantial context: the null-`level` data-quality caveat ('means not graded, never Beginner'), the plan-key requirement for card bodies, confirmation that this endpoint does NOT serve why-it-matters/key points, and the pointer to `_meta.available_categories`. This is exactly the beyond-annotation value the dimension rewards.

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 and return fields are front-loaded well, but the long parenthetical about the CHECK constraint and loader writing NULL (plus '108 of 330 were blank') is implementation history that costs more tokens than the takeaway ('null means not graded') requires. Structure is sound; sizing is inflated.

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 search tool with an output schema, four optional params, and annotations in place, the description still covers the data quirks an agent would otherwise trip on (null level, incomplete field set, paywalled body, external URL for omitted content). Nothing needed to call or interpret results correctly appears to be 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 already explains query word-matching, cursor reuse rules, category prefix behaviour, and the 50-row cap, so structured data carries the load. The description adds little about parameters beyond the `level` field's meaning and the warning to read `_meta.available_categories` rather than trusting prose, which largely duplicates the schema's category note.

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 SAP AI & analytics concept encyclopaedia') and enumerates the returned fields (slug, title, category, level, tags, summary). It explicitly positions itself against siblings: 'the same fields `get_concept` returns for ONE slug' and 'The card BODY ... call `get_concept_card`', so an agent can route 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?

Alternative routing is present and specific: `get_concept` for a single known slug, `get_concept_card` for the paid body, and citation_url for why-it-matters/key points. It never states the inverse case explicitly (i.e. 'use this first when you don't have a slug'), so it falls just short of full 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 cover readOnly/idempotent/closed-world safety, and the description adds substantial behavior beyond them: the free-key pagination requirement, the 10-row no-key cap, the `is_client` flag overriding the kind label, and the ordering logic (name-match tiers with query, quality ranking without).

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, then the flag caveat, then pagination, then ordering — a sensible order. It is dense but nearly every sentence carries a distinct rule; a minor trim of the flag/label emphasis would help, but nothing is wasted.

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 handling return shape and annotations covering safety, the description fills the remaining gaps an agent needs: exclusion semantics, pagination protocol, and ordering behavior. Complete 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 coverage is 100%, so the baseline is 3; the description earns extra by disambiguating the flag/kind-code distinction, explaining the module filter's selectivity and negative-result meaning, and the query word-matching rule. It restates some schema content, but the extra interpretive context is real.

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 Analytics Legends firm directory) and enumerates the kinds of organisations it covers, then explicitly contrasts with the sibling domain of SAP end-customers (find_sap_clients). An agent can distinguish this from find_sap_clients and get_firm without opening a 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 when-not (end-customer companies are excluded and live in a separate dataset), how pagination behaves with/without a key, and points to list_firm_kinds and count_firms_by for live vocabularies. The flag-vs-kind-label rule is called out as the deciding condition.

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

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

Annotations already establish read-only/idempotent/closed-world, and the description goes well past that: corpus composition (~84% general AI), the deterministic `scope` rule, the `citation_scope: "section_hub"` guarantee for every row, and the citation-vs-source_url contract. These are non-obvious output behaviours an agent could not infer from structured 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?

Purpose and the unfiltered-corpus warning are front-loaded, and the paragraphs follow a logical order (what it is → corpus skew → citation rules). It loses a point for the citation section, which restates the citation_url/source_url rule across three sentences with clear overlap.

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 and full annotations already present, the description still supplies the one thing those cannot: the corpus's actual composition and the citation trap. An agent has everything needed to call this correctly and to report 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 description coverage is 100%, so the schema already documents substring-per-word query matching, the dynamic category vocabulary, the SAC collision, and the inclusive date bounds — the description largely corroborates rather than adds. It does reinforce the cross-parameter strategy (filters needed for SAP questions, `match_count` scoping for quotable windows), but adds little new syntax-level meaning.

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

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

"Search the Analytics Legends market-news corpus" names a specific verb and resource, then immediately scopes it (SAP AI & analytics trade press) and disclaims what it is not ("NOT an all-SAP corpus"). No sibling tool covers news search, and the description makes that distinct role unmistakable.

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 guidance (pass `query` or `category` when the question is about SAP) and an explicit when-not (do not present an unfiltered page as 'the SAP AI & analytics news', do not present the hub as the article's page). This is prescriptive routing plus behavioural exclusions, not just implied usage.

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