Seventeen read only tools over cited company, portfolio and country data for bank credit desks.
Scored across 36 tools
Many tools target distinct resources, but several company_* and portfolio/deal tools have overlapping purposes (e.g., company_overview vs entity_risk_profile, company_financials vs company_financing, company_news vs company_social vs developments). Detailed descriptions help, but confusion remains across multiple ID spaces and similar-sounding tools.
All tool names follow a consistent snake_case convention with clear domain prefixes and predictable noun or verb_noun patterns. There is no camelCase or mixed style.
36 tools is well above the typical 3-15 range and likely to overwhelm an agent. While the platform covers many domains, many tools could be consolidated or grouped, making the count excessive for the apparent scope.
The surface covers a broad range of data retrieval for risk, portfolio, deals, tenders, news, and screening. However, it is read-only and some areas like detailed person profiles or workflow actions are absent, leaving minor gaps.
The delivery status of the workspace's alerts, newest first. Every attempt has a claim row (queued, or held_budget or held_quiet when it was not sent, digest when the fact arrived too old for an immediate alert) and an outcome row (sent or failed with its error_class). A delivered row means the receiver confirmed it (a signed webhook, or the SMS provider's final report), undelivered is the SMS provider's final negative report, and a dead_letter row closes an endpoint delivery whose failure is permanent or whose every retry is spent. Rows name the alert event by event_id and an endpoint by endpoint_id; a user's identity is not served. A key reads the deliveries of its own team's alerts and of workspace wide ones. Filter by event_id, status or channel. Paged with limit and offset; the response carries the exact total.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, default 50, maximum 100. | |
| offset | No | Rows to skip, default 0. | |
| status | No | Only rows with this status. | |
| channel | No | Only rows on this channel. | |
| event_id | No | Only the deliveries of this alert event. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive, and closed-world traits. The description adds substantial domain context beyond that: the claim/outcome row model, precise meanings of delivered, undelivered, and dead_letter, the auth scope (key reads its own team's and workspace-wide alerts), and pagination with an exact total.
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 front-loads the core purpose, and each subsequent clause conveys needed domain semantics for interpreting rows and statuses. It is dense and could be tightened, 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?
With no output schema and several custom statuses, the description supplies the return structure (claim and outcome rows), the meaning of each delivery state, the auth scope, and pagination behavior. Nothing material for correct invocation or interpretation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the claim/outcome row model and defining what statuses like delivered, undelivered, and dead_letter actually mean, which enriches the status enum and event_id parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource and ordering: 'The delivery status of the workspace's alerts, newest first.' It clearly separates deliveries from alert events by describing claim/outcome rows and endpoint status, but it never explicitly names the sibling tool alert_events as the alternative for event-level data.
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?
Usage is implied: the tool retrieves alert delivery status and supports filtering by event_id, status, or channel. However, there is no explicit statement of when to use this versus alert_events, and no when-not conditions or alternative routing are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The alert events of the workspace, newest first. Each names its event_class (risk_red, risk_amber, insolvency_notice, sanctions_candidate, tender_match, press_candidate or monitoring_finding), its severity (critical, high or info), the graph node_id and exposure_id of its subject, the source it stands on (source.kind and source.id), when the fact occurred and when the alert was written. An alert names ids only, never a name. A key reads its own team's events and the workspace wide ones. Filter by event_class or severity. Paged with limit and offset; the response carries the exact total.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, default 50, maximum 100. | |
| offset | No | Rows to skip, default 0. | |
| severity | No | Only events of this severity. | |
| event_class | No | Only events of this class. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/idempotent/non-destructive, and the description adds real behavioral context beyond them: newest-first ordering, that alerts carry ids only and never a name, the team-vs-workspace-wide visibility rule for a key, and that the response carries the exact total. This is genuine disclosure an agent cannot get 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?
Front-loaded with the resource and ordering, then the event contents and filtering. Dense but every sentence carries information; only the enum list restatement is arguably redundant with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description documents the returned fields (event_class, severity, node_id/exposure_id, source kind/id, occurrence and write timestamps), plus ordering, filtering, pagination and permission scope. Sufficient for correct invocation, though value-domain meaning (e.g. what risk_red vs risk_amber implies) is left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents limit, offset, severity and event_class with defaults and enums. The description's 'Filter by event_class or severity' and 'Paged with limit and offset' only restate what the schema provides, so 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 resource (alert events of the workspace) plus ordering (newest first) and the shape of each event. An agent can tell it is a read/list endpoint. It does not explicitly distinguish itself from close siblings such as alert_deliveries or developments, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage ('Filter by event_class or severity', paged) but never states when to choose this tool over alert_deliveries or company_events, nor any exclusion or prerequisite beyond the key-scope note. Usage must be inferred from the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The workspace's own audit log for a window of days: every recorded action with its time (UTC), action name, actor, target, run, model and details, in ledger order, including sign ins, single sign on provisioning and role changes, and member removals. Takes from and to as YYYY-MM-DD, both days included, at most 366 days. Needs an API key a workspace administrator issued with the audit scope; any other key answers forbidden. The export itself is recorded in the audit log. Large windows are cut at the output cap, so ask for shorter windows.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Last day, YYYY-MM-DD (UTC), included. | |
| from | Yes | First day, YYYY-MM-DD (UTC). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/idempotent annotations: discloses the authorization requirement (admin key with audit scope, forbidden otherwise), the self-referential side effect that the export itself is logged, and truncation at the output cap. None of this is available in the 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 the returned content, then moves to parameters, authorization, and limits. Dense but every clause carries information; a single long paragraph is slightly less scannable than a structured layout.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and only two parameters, the description compensates fully: it enumerates returned fields, the window format and cap, auth prerequisites, and truncation behavior. 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 coverage is 100%, so baseline is 3, but the description adds meaning the schema lacks – both days are inclusive and the window is capped at 366 days. It reinforces UTC handling rather than merely restating it.
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 (export) and resource (the workspace's own audit log) plus the exact fields returned – time, action name, actor, target, run, model, details, in ledger order. An agent knows precisely what this produces; no sibling covers the same ground.
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 operational context: needs an admin-issued API key with the audit scope, other keys answer forbidden, and large windows should be shortened. It does not name an alternative tool or an explicit when-not, but the constraints establish usage well.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The register event feed of one company: filings, status changes, and other register happenings, grouped into display rows and ordered by significance tier, each row citing its evidencing record where one exists. Takes node_id, the graph node id from search_companies hits. Related events arrive folded into one rollup row with a member_count and a group_key; pass that group_key as group to expand one rollup into its member events. A citation whose notice is set carries a text to show with the record; keep that notice with the record wherever it is quoted onward. For a company with a German register entry, insolvency_lookup states when your workspace last looked its German insolvency notices up (the portal allows single company lookups only, so they are only as complete as that lookup). Its state is pending while a lookup is queued (a company a person opened in the dashboard is looked up within minutes), then current with the date of the lookup; not_requested, with no timestamp, for a company no person of your workspace opened in the dashboard, screened, put into a dossier or holds in the portfolio, since reading this tool never asks for a lookup; and not_looked_up, with no timestamp, in any workspace where the lookups are not switched on. Show its note beside the feed.
| Name | Required | Description | Default |
|---|---|---|---|
| group | No | A group_key from a previous response; expands that one rollup into its member events. | |
| node_id | Yes | The graph node id, as returned by search_companies hits. Not the entity_id of company_profile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only/idempotent profile, and the description goes well beyond them: ordered significance tiers, folded rollup rows with member_count/group_key, citation notice carry-along rules, and a full insolvency_lookup state machine (pending/current/not_requested/not_looked_up) with its completion caveat.
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 feed/rollup behavior is front-loaded and useful, but the description runs long for a two-parameter read tool, with a dense multi-clause run-on describing insolvency_lookup states that could be tightened. Every sentence carries information, but parsing cost is high.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-shape burden and does so reasonably well: rows, citations, rollups, and the insolvency_lookup field with its note. A little more on ordering/pagination or row fields would make it fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both param descriptions are already present in the schema, including the node_id vs entity_id disambiguation. The description adds little on group beyond reiterating the expansion behavior, so the 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?
Names a specific resource (the register event feed of one company) and enumerates its content: filings, status changes, other register happenings. The row grouping, significance ordering, and citation behavior distinguish it clearly from siblings like company_news or company_records.
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 the agent to search_companies hits for node_id and warns against company_profile's entity_id, and explains when to pass group_key to expand a rollup. It does not, however, state when another sibling tool would be the better choice for adjacent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every financial figure for one company, newest reporting period first, each figure citing the source record it came from (a public register, a public filing repository, or the annual financial report the issuer published on its own website). Takes node_id, the graph node id carried by search_companies hits (not the entity_id of company_profile). Figures are served as filed at the source, except a figure with derived true, which the filing does not state and which was calculated from two figures the same filing states; its derivation says how in plain words. A missing period means nothing was filed, not zero.
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes | The graph node id, as returned by search_companies hits. Not the entity_id of company_profile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, it discloses real behavioral traits: figures are served exactly as filed, derived=true figures are not stated in the filing and were computed from two stated figures, and a missing period means nothing was filed rather than zero. These are non-obvious data semantics an agent could not 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-loaded with the return shape before the parameter, and every sentence carries information (id source, as-filed semantics, derived flag, missing-period meaning). The middle sentences are dense and could be split, 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 no output schema, the description fully carries the burden: it explains the ordering, source citations per figure, the derived flag, and the missing-period interpretation. An agent has everything needed to call and interpret this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema description already says node_id is the graph node id from search_companies, not entity_id. The description repeats rather than extends that, so the baseline 3 applies for a single fully documented parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource and scope (every financial figure for one company, newest reporting period first) and pins down the identifier source. It clearly distinguishes itself from company_profile and search_companies by naming the id each one carries.
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 routes the agent correctly by tying node_id to search_companies hits and warning against company_profile's entity_id, which implies the workflow. It stops short of stating explicit exclusions, e.g. when to prefer company_financing or company_public_funding over this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The debt surface of one company: registered charges with status lines and bound lenders, listed debt instruments, filed debt position facts, derived aggregates, a maturity wall, and per section coverage states saying how complete each section is. Takes node_id, the graph node id from search_companies hits. Long instrument books fold into the maturity wall; pass bucket (within_12m, 1_to_2y, 2_to_5y, beyond_5y, or no_maturity) to expand one maturity slice, and include_matured true to also list matured instruments.
| Name | Required | Description | Default |
|---|---|---|---|
| bucket | No | Expand one maturity-wall slice into its instruments. | |
| node_id | Yes | The graph node id, as returned by search_companies hits. Not the entity_id of company_profile. | |
| include_matured | No | Also list matured instruments, default false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is covered. The description adds genuinely new behavioral detail: that long instrument books are folded into the maturity wall, that per-section coverage states report completeness, and that matured instruments are hidden unless include_matured is set. It does not mention pagination or auth, hence not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the returned surface before parameters. Dense but every clause carries information; the long enumeration of sections is the only mild redundancy against the later 'coverage states' phrase.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of describing returns, and it does so by enumerating sections and coverage states. Annotations cover the safety profile and parameters are fully documented in the schema. Only the absence of any return-shape detail (e.g. pagination or error behavior) 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 the baseline is 3. The description adds value beyond the schema by explaining the mechanism behind bucket (long instrument books fold into the maturity wall, so bucket expands one slice) and by reinforcing that node_id is the graph node id rather than company_profile's entity_id.
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 resource ('the debt surface of one company') and enumerates exactly what it returns: registered charges, debt instruments, filed debt position facts, aggregates, maturity wall, and coverage states. This distinguishes it from siblings like company_financials, company_public_funding, and company_profile 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?
It tells the agent where node_id comes from ('the graph node id from search_companies hits') and explicitly warns it is 'Not the entity_id of company_profile', which routes the agent correctly. It also explains when to pass bucket and include_matured. It stops short of stating when to prefer this tool over company_financials or company_public_funding, so it is clear context without explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The register neighborhood of one node: its officers, shareholders and beneficial owners, its holdings, branches and other register relations, each edge citing the register record that states it (register, record type, identifier, source URL, retrieval date), current edges before closed ones. Takes node_id, the graph node id from search_companies hits or from a previous network answer, so a neighbor expands the same way. Natural persons are served, with node_type person, only in workspaces where person data is switched on; elsewhere they and their edges are left out, and a person node_id answers not_found. edge_types keeps the named types only (for example officer_of,owns); limit caps the neighbors, default and maximum 200, and truncated says when it cut.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum neighbors, default and maximum 200. | |
| node_id | Yes | The graph node id, as returned by search_companies hits. Not the entity_id of company_profile. | |
| edge_types | No | Comma separated edge types to keep; omit for every type. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the read-only/idempotent profile, and the description adds substantial behavior: person nodes served only where person data is enabled and otherwise omitted with not_found, edges carry register citations with record type/identifier/URL/retrieval date, current edges ordered before closed ones, and a truncated flag on limit cuts.
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?
Dense and front-loaded: the node's neighborhood is stated first, then sourcing, then person-data gating, then parameters. It is a long run-on paragraph, but nearly every clause carries non-redundant 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 no output schema, the description takes on return-shape disclosure by naming the per-edge citation fields, ordering, and truncation behavior, plus the person-visibility caveat — everything an agent needs to call and interpret it.
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 already 100%, but the description still adds value by giving example edge type values (officer_of, owns), confirming limit's default/max of 200, and describing the truncated signal.
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 register neighborhood of one node') and enumerates the edge classes returned (officers, shareholders, beneficial owners, holdings, branches), which cleanly separates it from siblings like company_profile and ownership_chain.
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?
Explains that node_id comes from search_companies hits or a previous network answer and that neighbor expansion works the same way, giving clear triggering context. It stops short of explicitly naming when a different sibling (e.g. ownership_chain) should be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Global news coverage of the companies the workspace holds in its book or watches, and of the natural persons it watches where person data is switched on (node_type person), read from the GDELT Project's 15 minute files in English and machine translated from about 65 languages. Without node_id it lists the companies, each with its newest reading of a day read in full (the day in progress is never read in full and reads feed_gap), or latest null while no reading is stored, which says nothing about coverage. With node_id it returns that company's daily readings, newest first (days, default 30), and the newest 100 articles behind the newest one together with every article its events list: article_key, url, publisher_host, published_at, language, gdelt_tone and the matched_organization name. A reading's state is reading (tone_mean is the mean GDELT document tone of the articles in the 30 day window, article_keys cite the newest 100 of them and articles_window counts them all), too_little_coverage (fewer than three articles in a fully read window, no tone) or feed_gap (the day or a thin window not fully read, no tone). Tone is context beside the credit view and never part of the risk score. With node_id it also returns events, the company's serious news events of the same days: event_type (insolvency, sanctions, fraud, cyberattack, accident, legal_action, executive_exit, layoffs, strike or environment_rights, from GDELT's own theme codes under a reviewed mapping, never a model), severity, opened_at, detected_at, closes_at, the articles, independent sources and languages behind it, whether it raised an alert, the article_keys of its newest 20 articles, and its check: before any alert a model reads the event's articles and a deterministic gate keeps its verdict only when the cited article is one of the event's own and the quote is found in it verbatim; status is confirmed (only such an event alerts), not_confirmed (news to read, not a finding), pending, unchecked (the check could not run, no alert went out) or covered, with verdict, the checked event_type, the cited article_key, reason, model, prompt_version, checked_at and second_source_articles, the NewsAPI.ai articles the check read beside the event's own (article_key, url, publisher_host, published_at, language, provider), empty while that source is off. No headline, article text or quote is kept, and no person name beyond the matched name of a followed person. A watched person is read for the due diligence the bank runs on that person, its tone context and never a score of the person. A sole trader (sole_trader true, a natural person's business) carries no tone, so latest is null, readings are empty and gdelt_tone is null, while its articles and events are served. Neither is ever scored. Every answer carries the GDELT attribution to show with the data. A company outside the workspace's book and watch list answers 404.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Daily readings to return with node_id, default 30. | |
| limit | No | Page size, default 50, maximum 100. | |
| offset | No | Rows to skip, default 0. | |
| node_id | No | The company's graph node id; omit to list companies. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond readOnly/idempotent/closed-world annotations, the description discloses a wealth of behavior: the day in progress is never read in full and reads feed_gap, reading states (reading/too_little_coverage/feed_gap) with their tone and article-key semantics, the deterministic verbatim-quote gate and its status enum, that no headline/text/quote or person name is retained, that sole traders carry no tone, and the required GDELT attribution. This is genuinely additive context an agent could not get from annotations 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?
Almost every clause carries substantive information, and the coverage statement is front-loaded, but the body is one enormous run-on paragraph with nested parentheticals that is hard for an agent to parse. Length is defensible given the tool's complexity, yet structure (headings or bullets for list vs detail vs events) would make it far more usable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly bears the full burden of describing returns and does so exhaustively — reading fields, tone_mean window, article_keys vs articles_window, event fields, check verdict fields, and status meanings. Nothing an agent needs to interpret a response appears 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 four parameters including defaults and ranges are already documented, making 3 the baseline. The description restates days (default 30) and node_id's list-vs-detail behavior without adding syntax or format detail beyond the schema, so it adds little new parameter 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 description names a specific verb+resource stack — GDELT-sourced global news coverage of book/watchlist companies and watched persons, returning daily readings, articles, and serious news events with verdict checks. An agent can tell exactly what data comes back. It does not name siblings, but the resource and output shape are 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 draws a clear behavioral fork on node_id (omit to list companies, supply to get readings/articles/events) and notes the 404 boundary for out-of-scope companies. However it never says when to reach for this tool versus overlapping siblings such as company_events or company_social, which also surface company news and events. Usage is implied through parameter branching rather than stated as 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.
One company the way the dashboard's Network view shows it, by node_id, the graph node id carried by search_companies hits (not the entity_id of company_profile). Answers the register identity, what the register records held for the company state (GLEIF, Companies House, a German register extract where one was read, SEC EDGAR, the Swiss gazette and the Marktstammdatenregister operator) in plain words, each fact with the record it cites and when that record was last confirmed, and the risk status. risk_state is portfolio when your team holds the company (risk then carries its portfolio assessment, as entity_risk_profile returns it), assessed when an assessment was made on the spot for your team, in_progress while one is being made, not_assessed with risk_reason allowance, failed or not_started, or sole_trader when the register states a natural person's business, which is never scored (risk then carries sole_trader true and no assessment). A tool call reads only and never starts an assessment. Pass locale de for the German field labels.
| Name | Required | Description | Default |
|---|---|---|---|
| locale | No | The language of the field labels, en by default. | |
| node_id | Yes | The graph node id, as returned by search_companies hits. Not the entity_id of company_profile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry readOnly/idempotent/non-destructive, but the description adds real context: it never starts an assessment, every fact is tied to a citing record with a last-confirmed timestamp, and it fully enumerates risk_state semantics including sole_trader never being scored. This goes well beyond the structured hints, though it does not describe pagination or response framing.
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 is a dense wall of semicolon-separated clauses (the risk_state enumeration in particular) that is hard to scan. Some of this detail earns its place with no output schema, but the presentation is not structured for quick parsing.
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 tool with no output schema, the description supplies the return shape (plain-word facts plus citations/confirmation dates), the register sources, and complete risk_state semantics. Coverage is strong; a brief note on what happens when no record exists would close the remaining gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents node_id (graph node id from search_companies, not entity_id) and locale (en default). The description largely repeats those semantics; 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?
States a specific resource (one company as the dashboard's Network view shows it) and keys it to node_id, explicitly distinguishing it from company_profile's entity_id and from search_companies. An agent can tell exactly which of the ~35 siblings to call given a node_id.
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 the trigger (a node_id carried by search_companies hits, not company_profile's entity_id) and the read-only/should-not-be-used-for-assessment boundary. It implies, rather than explicitly maps, the alternative to use when the caller holds an entity_id instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One registry row's identity from the closed Stonewake registry of named market participants (export credit agencies, multilaterals, development finance institutions, development banks, government agencies and banks, plus the trade publications deals cite): slug, display name, full name, kind and its label, country and location, aliases, and group memberships. Takes entity_id from the registry's own id space. This is NOT the node_id that search_companies returns and entity_risk_profile takes; the two id spaces are different, and an id from the wrong space answers not_found.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_id | Yes | The registry entity id. Not a graph node_id from search_companies. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive and closed-world; the description reinforces the closed registry and adds genuinely new behavior: the two-id-space rule and the not_found failure mode. It does not describe empty-vs-error responses or any rate/permission constraints, so it stops short of fully rich disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the returned identity fields and then the id-space caveat. The field enumeration is long but each item earns its place; the em-dash parenthetical listing participant kinds could be trimmed without loss.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates well by enumerating the returned fields, and the annotations carry the safety profile. A single required parameter is fully explained. Complete enough to call correctly, though the returned-field list is not a formal contract.
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 itself already warns that entity_id is not a graph node_id, so the description is partly redundant. It still adds value by tying the id to the registry's own space and to the not_found consequence, which is more than the schema sentence says.
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 the specific resource (one registry row's identity) and enumerates exactly what is returned: slug, display name, full name, kind and label, country/location, aliases, group memberships. It explicitly distinguishes itself from search_companies and entity_risk_profile by id space, so an agent can tell the three apart 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?
Clear guidance on the discriminating condition: it takes entity_id from the registry id space, not the node_id that search_companies returns or entity_risk_profile takes, and warns that a wrong-space id answers not_found. It does not, however, say when to prefer this over sibling profile reads such as company_overview or company_records, so the routing is strong on the id dimension but silent on the profile-vs-profile dimension.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Public grants and state aid one company received, from the EU State aid Transparency Award Module, Kohesio and the Financial Transparency System, with totals per year and per programme. Takes node_id, the graph node id from search_companies hits. Each award cites its source record and states how it was bound to the company, always by an identifier and never by a name alone. Totals never add figures of a different basis or currency, and a range a source states stays a range (band_low_total and band_high_total). The tool reads only awards to organisations. State aid figures from TAM are aid granted, not aid paid, published only above the threshold of each measure and never for de minimis aid, and for a loan or a guarantee a figure may be the loan or guarantee itself.
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes | The graph node id, as returned by search_companies hits. Not the entity_id of company_profile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial behavioural detail beyond them: award provenance and citation, the guarantee that binding is by identifier and never by name alone, the aggregation rule that totals never mix bases or currencies, preservation of ranges as band_low_total/band_high_total, and the critical caveat that TAM figures are aid granted (not paid), above threshold, excluding de minimis, and may represent the loan or guarantee itself. This is exactly the kind of non-obvious semantics an agent cannot get from 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?
It is front-loaded with the resource and sources before moving into caveats, and every sentence carries information an agent could act on. It is dense and on the long side, but the length is justified by the number of distinct data-semantics warnings; little is padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the burden of describing returns — and it does: per-year and per-programme totals, source citations, binding method, and range representation via band_low_total/band_high_total. Combined with the annotation coverage of the safety profile and a fully documented single parameter, an agent has everything needed to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With one parameter and 100% schema coverage, the baseline is 3; the description earns above that by clarifying the identifier's origin (graph node id from search_companies hits) and explicitly warning against the plausible mistake of passing company_profile's entity_id. It adds genuine disambiguation rather than repeating the schema text.
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 resource (public grants and state aid received by one company) and enumerates its sources (TAM, Kohesio, Financial Transparency System) plus the shape of what comes back (totals per year and per programme). That is far more specific than a restatement of the title. It stops short of explicitly separating itself from adjacent siblings such as company_financing or company_financials, so an agent still has to infer which funding-flavoured tool applies.
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 does give one concrete usage instruction — node_id comes from search_companies hits — and rules out a wrong-looking alternative ('Not the entity_id of company_profile'). It also narrows scope with 'reads only awards to organisations'. However, there is no statement of when to reach for this tool versus company_financing, company_financials or company_overview, so alternative selection is left implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The register records behind one company, a page at a time. Each row is a citation (register, record type, identifier, source URL, retrieval date), newest first. Takes node_id, the graph node id from search_companies hits. Every page states records_total, the company's whole count, and registers, each register's connector_id, name and count; pass one connector_id to page that register alone. A company listed in a securities register can hold over 100,000 records, so page with limit (default and maximum 25) and offset, and read registers first to decide what to page. A row whose notice is set carries a text to show with the record; keep that notice with the record wherever it is quoted onward.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, default and maximum 25. | |
| offset | No | Rows to skip, default 0. | |
| node_id | Yes | The graph node id, as returned by search_companies hits. Not the entity_id of company_profile. | |
| connector_id | No | One register to page, as a registers row names it; omit it to page every register newest first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: pagination discipline (default and max 25), the ordering (newest first), per-page aggregates (records_total, registers with connector_id/name/count), and a retention obligation on notice text that must travel with quoted records. It stops short of describing error or empty-page behavior, so a 4 rather than a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with resource and row shape, then paging mechanics, then the notice obligation. Dense but nearly every clause carries information; the notice sentence is the one piece that sits slightly apart from the call itself.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries return-shape responsibility and discharges it: rows are citations with register, record type, identifier, source URL and retrieval date, plus page-level records_total and registers. Combined with the paging and volume guidance, an agent has everything needed to call it correctly and interpret the 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%, so baseline is 3. The description still earns above baseline by disambiguating node_id ('the graph node id from search_companies hits', explicitly not company_profile's entity_id) and by framing connector_id as selecting one row out of the registers list rather than as an opaque filter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific resource (the register records behind one company) with explicit scope (a page at a time) and row shape. It also draws a hard line against siblings by stating node_id comes from search_companies hits and is 'Not the entity_id of company_profile', so an agent can separate it from the many company_* tools 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?
Gives concrete when-to-use guidance: read the per-page registers list first to decide what to page, then optionally pass a single connector_id to page just that register. It also notes the fallback (omit connector_id to page every register newest first) and warns of the >100,000-record case that forces limit/offset paging.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Official regional statistics beside one German company: the VGR der Länder tables of the Kreis (GDP, gross value added by industry, employment, population) and the Zensus 2022 housing figures of the Gemeinde and the Kreis (rents, vacancy, building age) its seat lies in, and the Regionalatlas indicators of the Kreis (population movement, business registrations and insolvencies, unemployment, disposable income), the BA labour market figures of the Kreis (registered unemployed, underemployment, the newest 13 months) and the Regionaldatenbank tables of the Gemeinde and the Kreis (corporate insolvencies by WZ 2008 section, Hebesätze), each with its table, period, retrieval time, source link and the attribution line, which must be shown with the figure. Takes node_id, the graph node id from search_companies hits. The seat is the register seat; only when no register extract states one is it the seat a German insolvency notice states, and region.seat_label then says so with the notice date. region states how the seat was joined to its official key (an exact name match only), or why no region is determined; missing lists in plain sentences what is not held. Aggregates for context only, never part of the company's score or status.
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes | The graph node id, as returned by search_companies hits. Not the entity_id of company_profile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive safety, so the description need not restate that. It adds genuine behavioral context beyond the annotations: how the seat is determined (register seat, falling back to insolvency-notice seat with region.seat_label noting the notice date), how the region is joined (exact name match only), what 'missing' reports, and the mandatory attribution line. These are real operational traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The content is front-loaded with the returned datasets, but the description is essentially one enormous run-on sentence bundling five data sources, seat logic, join logic, and output-field semantics. It is dense to the point of being hard to scan, so structure and conciseness fall short.
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 tool with no output schema, the description covers what each returned source contains (table, period, retrieval time, source link, attribution), the seat-resolution edge case, the join caveat, and the missing-list behavior. An agent has enough to call it correctly, though the run-on phrasing leaves some detail tangled.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single node_id parameter is fully documented in the schema. The description echoes the schema ('the graph node id from search_companies hits') without adding syntax or format detail, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource (official regional statistics for a German company's seat) and enumerates the concrete data sources: VGR der Länder, Zensus 2022, Regionalatlas, BA labour market, Regionaldatenbank. It is clearly a retrieval/context tool and does not overlap with siblings like company_sector_context. The density makes it slightly hard to parse, but the purpose is 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 states the argument source ('the graph node id from search_companies hits') and the caveat that results are 'for context only, never part of the company's score or status', which implies when to consult it. However, it never explicitly contrasts itself with siblings such as company_sector_context or country_profile, so the when-to-use guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Official German statistics beside one German company: the corporate insolvency and enterprise figures Destatis publishes for its WZ 2008 section and its Bundesland, each with its table code, period, retrieval time, source link and the licence attribution line, which must be shown with the figure. Takes node_id, the graph node id from search_companies hits. No German register states a company's NACE code, so pass nace (a section letter or a NACE code such as 41.20) to name the sector; the answer then says the caller named it. missing lists in plain sentences what is not held, Kreis level included. Aggregates for context only, never part of the company's score or status.
| Name | Required | Description | Default |
|---|---|---|---|
| nace | No | A NACE or WZ 2008 code naming the sector, for example F, 41 or 41.20. | |
| node_id | Yes | The graph node id, as returned by search_companies hits. Not the entity_id of company_profile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only/idempotent annotations, it discloses the return shape (table code, period, retrieval time, source link), a compliance obligation (the licence attribution line must be shown with the figure), the 'missing' field's plain-sentence behavior including Kreis level, and provenance labeling of a caller-supplied sector. That is rich behavioral context an agent cannot get 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?
Front-loaded with what the tool returns, then parameters, then the caveat, so the most important information leads. The prose is dense and slightly run-on, and it is long for a two-parameter tool, but with no output schema most sentences carry needed 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 no output schema and only annotations for the safety profile, the description covers returns, the licence-attribution duty, the missing-data field, and the scoring caveat, leaving nothing an agent needs in order to call and interpret it.
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 already 100%, so the baseline is 3, but the description adds real rationale: why nace must be supplied (no register holds NACE) and that the response records the sector as caller-named. It reinforces node_id's provenance, though that partly repeats the schema text.
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: it returns the Destatis corporate insolvency and enterprise figures for a company's WZ 2008 section and Bundesland. It distinguishes itself from company_profile by clarifying node_id is not entity_id, but it never names the obviously adjacent sibling company_regional_context, so the sector-vs-region boundary is left for the agent to infer.
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 context: take node_id from search_companies hits, and pass nace to name the sector because no German register states a company's NACE code. It also supplies a clear when-not caveat ('aggregates for context only, never part of the company's score or status') but does not explicitly route the agent away from company_regional_context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What is said on social platforms and forums about the companies the workspace holds in its book or watches, and the natural persons it watches where person data is switched on (node_type person), read from a licensed social listening source. Every answer carries source.enabled; while it is false no source is switched on and nothing current is read. Without node_id it lists the companies, each with its newest reading of a day read in full, or latest null while no reading is stored. With node_id it returns that company's daily readings, newest first (days, default 30), and its newest 100 items of the last 30 days: item_key, platform, url (null with link_withheld true when every form of the link would name a person), published_at, language, the source's sentiment label and the matched_name. A reading counts the items of its 30 day window per platform and by sentiment (YouTube items are listed, never counted); its state is reading (sentiment_net is positive minus negative over the rated items, from -1 to +1), too_little_coverage (fewer than three rated items in a window read in full, no sentiment) or feed_gap (the day or a thin window not read in full, no sentiment). No author, handle, title or post text is ever kept. A watched person is read like any company, its reading context for the bank's due diligence on that person and never a score of the person. A sole trader (sole_trader true, a natural person's business) carries no sentiment, so readings are empty, latest is null and each item's sentiment is null, while its items are listed. A company's reading is context beside the credit view, and no reading is ever part of the risk score. A company outside the workspace's book and watch list answers 404.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Daily readings to return with node_id, default 30. | |
| limit | No | Page size, default 50, maximum 100. | |
| offset | No | Rows to skip, default 0. | |
| node_id | No | The company's graph node id; omit to list companies. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already covering the read-only, idempotent, non-destructive safety profile, the description adds substantial operational context: the source.enabled gate, privacy constraints (no author, handle, title or post text retained; link_withheld), the sentiment state machine (reading / too_little_coverage / feed_gap) with rating thresholds, sole_trader behavior, and the explicit statement that readings never feed the risk score. This is exactly the kind of context annotations cannot carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The content is largely front-loaded and almost every clause carries real information, but it is delivered as a dense wall of run-on sentences mixing enumeration behavior, privacy rules, sentiment semantics and edge cases. It is exhausting to parse and would benefit from structure, which is the definition's main weakness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, yet the description documents return shapes in detail: list mode (each company's newest reading or latest null) and detail mode (reading fields, the newest 100 items with item_key, platform, url, published_at, language, sentiment label, matched_name), plus edge cases for sole traders and feed gaps. An agent has everything needed to call and interpret it.
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 four parameters, and limit/offset receive no additional meaning in the description. The description does add real value for days (default 30, newest-first) and node_id (omit to list companies), so it earns the baseline but not more.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific resource (social/forum chatter about book companies and watched persons) and a specific source (a licensed social listening source), which cleanly separates it from siblings like company_news, company_events and developments. The two operating modes (list companies without node_id, return daily readings with node_id) are stated up front.
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?
Clearly explains the two invocation modes and the key precondition (source.enabled must be true or nothing current is read), plus the 404 for companies outside the book/watch list. It stops short of explicitly naming an alternative sibling (e.g., company_news) for news-style content, so the agent must infer routing rather than being told.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Country intelligence for export finance. Without iso3 this returns the index of covered countries with each one's risk score and the caller team's live deal rollup. With iso3 (a three letter ISO 3166-1 alpha-3 code such as TUR) it returns one country in depth: the risk score with its cited component breakdown, indicator values, membership lists with legal citations, reference events, and the team's deals there. The deal fields are filled only for a workspace with the deals module; without it they read zero and empty, which says nothing about deals in that country, so never report them as no deals. Indicator and dataset entries carry attribution fields such as attribution_text stating the data licence terms; preserve that attribution whenever values are quoted onward.
| Name | Required | Description | Default |
|---|---|---|---|
| iso3 | No | ISO 3166-1 alpha-3 country code; omit to list every covered country. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only/idempotent safety profile, yet the description adds substantial non-structured context: deal fields read zero/empty when the workspace lacks the deals module and that result must not be interpreted as 'no deals', plus a data-licence obligation to preserve attribution_text when quoting onward. That is exactly the operational nuance the annotations cannot express.
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 tool's purpose, then the no-iso3 case, then the iso3 case, then the caveats and attribution duty — a logical ordering with no filler. It is a dense single paragraph rather than scannable structure, and one sentence could be split, but every sentence contributes 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?
There is no output schema, so the description carries the full burden of describing return shape, and it does: index fields (risk score plus team deal rollup), depth contents (component breakdown, indicator values, membership lists with citations, reference events, deals), plus the misleading-empty edge case. An agent has everything needed to call and interpret it.
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 iso3 and its omit-to-list behavior, so the baseline is 3. The description still adds value with a concrete format example ('TUR'), the full ISO 3166-1 alpha-3 reference, and the downstream consequence of each mode, which is more than the schema states.
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 resource ('country intelligence for export finance') and exhaustively enumerates the two return modes keyed off the iso3 parameter, with concrete contents for each. An agent can tell exactly what this returns without opening the schema, and it is clearly distinct from company_profile or entity_risk_profile siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the condition that selects each mode: omit iso3 to get the covered-country index, supply iso3 for a single country in depth. It also gives a clear do-not ('never report them as no deals'). It stops short of naming alternative sibling tools for adjacent needs such as risk scoring or company lookups, so no explicit alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The parties on the caller team's live deals that are not yet matched to a company in a register, the worklist the dashboard shows behind Match parties to a register. Followed deals come first, then the parties flagged because two or more companies hold the identifier a person entered (flagged_identifier names it), then the parties with candidate companies. Each row names its deal (deal_id, deal_name, deal_followed), its team (team_id, team_name), the party's role and name, whether a person already chose none of the candidates (dismissed), and the candidates, each a company with node_id, label, country_iso3 and up to three identifiers, the LEI first. Pass deal_id to read one deal's parties; a deal outside the caller's team reads as an empty page. Paged with limit and offset; the response carries the exact total. Matching a party happens in the Stonewake dashboard.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, default 50, maximum 100. | |
| offset | No | Rows to skip, default 0. | |
| deal_id | No | Only this deal's parties, a deal_id as deal_book rows carry it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already covering the safe-read profile (readOnly, idempotent, non-destructive, non-open-world), the description still adds substantial behavioral context: the exact ordering (followed deals first, then flagged_identifier matches, then candidates), team scoping that turns out-of-team deals into an empty page, and pagination with an exact total. This is well beyond what the annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose is front-loaded, and the length is justified by the absence of an output schema, since the row structure must be described. The middle sentence is a dense enumeration of fields, which weakens readability, but no sentence is purely redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the full burden of explaining return values, and it does: it enumerates each row's deal, team, party, dismissed flag, and candidate fields (node_id, label, country_iso3, identifiers with LEI first). Combined with ordering, pagination, and scoping notes, it is complete for the task.
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 baseline is 3. The description still adds meaning: 'Pass deal_id to read one deal's parties' clarifies intent, and the scoping note that a deal outside the caller's team reads as an empty page gives semantics the schema alone does not 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?
The description precisely defines the resource: the parties on the caller team's live deals that are not yet matched to a company in a register, and explicitly frames it as the worklist behind 'Match parties to a register'. This distinguishes it from siblings like deal_book or portfolio_book, which cover broader deal data. It is a noun-phrase definition rather than a verb+resource phrasing, but the scope is 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?
Usage is implied: fetch unmatched parties via this queue, pass deal_id for a single deal, and note that actual matching occurs in the Stonewake dashboard. However, no explicit when-to-use-this-vs-alternative guidance is given against siblings like deal_book, so the agent must infer the selection boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The deal book of the one team the caller's key reads; every row names that team (team_id, team_name). Without deal_id this lists deals ordered by their ranking window first (financing open, early stage, not confirmed, financing closed, cancelled) and the score inside it unless sort names one column, filterable by stage, window, country_code (ISO country codes), sector, status, eca, eca_named (only deals naming an export credit agency), minimum contract value (min_value_usd), and free text (q); sort is priority (the default, the window order above) or one column that orders the whole filtered book, score, value (the USD value), last_activity, stage (the pipeline order), name or first_seen, with direction desc (the default) or asc and rows without a value last, or latest_update, which ignores the window and orders by the newest dated event, rows without one last, desc only; paged with limit (default 50, maximum 100) and offset, with the exact total. Dismissed deals are excluded unless status asks for them, and the portfolio rows a desk holds back by default (closed, cancelled, older than the stale window of 12 months by default, own bank, domestic; score_hidden true) are off the page unless include_hidden is true, and score_own_bank marks the rows where your own bank is a lender. A row carrying merged_into was found to be a duplicate and folded into the deal that field names: read that deal instead, and expect this one to be dismissed. Each row carries its window (score_window and its label), the band word and reason count behind its score (score_band, score_reason_count), the confirmed state over its linked findings (state, state_label), the newest quote backed event date (event_date, null when no source stated one), the lender names on the deal (lenders), and the two derived sentences a desk reads first: angle (why the row is on the list) and ask (what is still to be financed, read from the confirmed state, the window, the agencies and the lenders; a row whose state no source confirmed reads State not confirmed by a source yet), latest_update (the newest event a source dated and confirmed, with its date, a short label naming the confirmed state and the amount only where a quote states it, the state and the finding_id it rests on, null when there is none) and has_unseen_update (true when that event reached the deal after your last open of it in the dashboard, null for an API key, which records no opens). With deal_id (the deal_id field of list rows) it returns one deal in full, with score_reasons, one plain sentence per scoring component saying which fact it matched, alongside parties carrying entity_id and node_id where bound, the cited timeline with press quotes (each entry also carrying the state its quote confirmed, the confirming passage and the event date), lifecycle events, sources each carrying source_tier (1 a primary source, 2 trade press, 3 an aggregator, which is also where an unclassified publisher lands) and its tier_label, the deal summary (summary_lines, three lines generated from the cited findings by fixed rules, not by a model, each with the finding and quote behind every field it states), the briefing (null, or text, drafted_at, drafted_by, which reads model, and sources, a quick summary an AI model drafts from the text of the deal's cited sources with those sources listed by source_id, url, publisher and published_at, only its numbers written in digits checked against that text, null until it is drafted, whenever no sentence passes its check, and when nothing is left once a clause asking the reader to confirm, verify, check or review anything is removed), the analyst's own next_action, and economics.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Free-text filter over deal names and summaries. | |
| eca | No | Keep only deals naming this export credit agency. | |
| sort | No | The order, default priority (the ranking window first). latest_update orders by the newest dated event, whatever the window. Any other value orders the whole filtered book by that one column. | |
| limit | No | Page size, default 50, maximum 100. | |
| stage | No | Keep only these lifecycle stages. | |
| offset | No | Rows to skip, default 0. | |
| sector | No | Keep only these sectors. | |
| status | No | Keep only these statuses; dismissed deals appear only when asked for here. | |
| window | No | Keep only these ranking windows: financing_open, early_stage, not_confirmed, financing_closed, cancelled. | |
| deal_id | No | A deal_id from the list; when present the other arguments are not used. | |
| direction | No | desc (the default) or asc. The priority and latest_update orders read desc only. | |
| eca_named | No | Keep only deals naming an export credit agency. | |
| country_code | No | Keep only deals in these ISO country codes. | |
| min_value_usd | No | Keep only deals at or above this contract value in USD. | |
| include_hidden | No | Also serve the rows a desk holds back by default (closed, cancelled, older than the stale window, own bank, domestic); off by default. |
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 adds substantial non-obvious behavior: dismissed deals excluded unless status asks, desk-held rows off the page unless include_hidden, merged_into meaning the row is a folded duplicate to be dismissed, has_unseen_update null for API keys, and the exact conditions under which briefing is null. This is far more than the annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The content is dense and mostly earns its place for a 15-parameter dual-mode tool, but it is delivered as one monolithic paragraph of semicolon-chained clauses, which harms parseability and front-loading after the first sentence. A structured breakdown (list mode, detail mode, filters, sorts, hidden rows) would be far more usable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and 15 parameters, the description carries the full return-value burden and does so thoroughly: list-row fields (window, band, state, event_date, lenders, angle, ask, latest_update, has_unseen_update) and detail-mode fields (score_reasons, parties, timeline, sources with tiers, summary_lines, briefing, next_action, economics). An agent has enough to call and interpret results correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter semantics the schema does not: the priority window ordering, that latest_update ignores the window and reads desc only, that rows without a value sort last, and the interplay of include_hidden with score_hidden and score_own_bank. That materially deepens meaning beyond the per-field schema text.
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 scope ('the deal book of the one team the caller's key reads'), and the description clearly splits into two modes: a filtered list without deal_id and a single full deal with deal_id. It implicitly distinguishes itself from the portfolio/hidden-row siblings via the include_hidden and score_hidden discussion, but never names an alternative tool outright.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit mode-selection guidance ('Without deal_id this lists deals...', 'With deal_id... returns one deal in full, with...'), plus default sort, direction constraints, exclusion rules and stale-window behavior. What it lacks is explicit routing against sibling tools such as portfolio_book or deal_duplicates, which an agent would need to disambiguate similar books.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dated, cited developments surfaced by your team's research runs, the runs of the one team the caller's key reads: grounded findings with a headline, category, verification state, and corroborating source count. Without run_id this is a feed paged with limit (default 25, maximum 100) and offset, with the exact total; sort is recent (default) or score. Each row names the run_id it came from and its team (team_id, team_name); pass run_id to load that whole research run with its grounded findings, press quotes, and cited sources. Another team's run_id answers not found, like an unknown one. A run about a natural person is served only where person data is switched on, and its rows carry no relevance score and are never ordered by one.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Feed order: recent (default) or score. | |
| limit | No | Page size, default 25, maximum 100. | |
| offset | No | Rows to skip, default 0. | |
| run_id | No | A run_id from a development row; when present the other arguments are not used. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive, closed-world, so the safety profile is covered. The description goes further with real behavioral context: exact total returned, default/max page size, sort default, cross-team access returning not-found, and person runs lacking a relevance score and never ordered by one. It omits whether results are cached or how fresh they are, but this is well above the annotation baseline.
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 the feed/run_id split are front-loaded before any caveats, and most clauses carry information. The second and third sentences are long and dash-heavy, bundling return-shape, error behavior, and person-data gating into single sprawling sentences, which costs a little readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the full burden and does so: it names the row fields (headline, category, verification state, corroborating source count, run_id, team_id, team_name), the paging contract, the sort options, and the special case for natural-person runs. An agent has enough to call it correctly and interpret the 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%, including the sort enum values, limit bounds, offset, and the note that run_id causes the other arguments to be ignored. The description largely restates this (default 25, maximum 100, sort recent/score) rather than adding syntax or format meaning, so the baseline 3 applies despite the added detail on row-level fields like run_id and team_id/team_name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening states a specific resource ('dated, cited developments surfaced by your team's research runs') with a clear noun phrase, and it immediately distinguishes the two modes (feed vs. single-run load) that a sibling tool would otherwise have to cover. An agent can tell what this returns and how it differs from search_stonewake_docs or company_news without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when each mode applies: omit run_id for a paged feed, pass run_id to load that whole research run. It also names the failure condition (another team's run_id returns not found, like an unknown one) and the gating condition for person-related runs. There is no reliance on inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The caller team's credit-risk view of one company, by its graph node_id (the id search_companies hits carry). Answers one of three honest shapes: not in the portfolio (in_portfolio false), held but not yet assessed (assessment null), or the full current assessment with its status band, score, seen_share, explained_share and reachable_share (the figure the insufficient floor reads), a coverage_line of one to three sentences counting covered signals and gaps with their reasons, and every signal with its state (evidenced, register_quiet, gap, awaiting_bank_input, not_applicable), gap_reason, evidence grade (A to D), evidence value, note, and citation ids. A signal no connected source reaches for the company's jurisdiction is a gap, never not_applicable. A held company also carries entity_class: the class its checks route on (a bank is never scored on corporate distress models) and its source, either your team's analyst override or the register rule that derived it. A sole trader (sole_trader true, a natural person's business by its register's evidence) is never scored: assessment and entity_class are null. Company nodes only; person lookups answer not_found.
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes | The graph node id, as returned by search_companies. Not the entity_id of company_profile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/idempotent annotations by enumerating the three possible response shapes (not in portfolio, held-but-unassessed, full assessment), the signal state vocabulary, the jurisdiction gap rule, entity_class routing semantics, and the sole_trader null-scoring behavior. This is exactly the behavioral detail annotations cannot carry.
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 identifier are front-loaded in the first clause, and the dense tail earns its place by enumerating return values that have no output schema. However it is delivered as one long run-on paragraph, so heavy enumeration of states and grades is harder to scan than a structured list would be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema available, the description carries the full return-value burden and does so thoroughly: shapes, signal states, gap_reason, evidence grade A-D, citation ids, entity_class, and the sole_trader null case. An agent has everything needed to interpret results 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?
Single parameter with 100% schema coverage, so the schema already documents type and bounds; the description nonetheless adds real meaning by identifying it as the graph node id returned by search_companies and warning it is not company_profile's entity_id.
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 ('the caller team's credit-risk view of one company') and pins the identifier ('by its graph node_id'), explicitly contrasting it with company_profile's entity_id. An agent can distinguish it from search_companies, company_profile and company_financials 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 a clear usage context (fetch the team's risk view for a known company node) and one concrete exclusion ('Company nodes only; person lookups answer not_found'), plus the routing hint that the id comes from search_companies. It stops short of naming an explicit alternative tool to call instead for held/assessed versus unheld cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One exposure's credit review history, newest first, so the first item is the standing review and each later one the review it superseded. Each review carries its disposition (no_action, watch_list, intensified_care or escalated), note, next review date and when it was recorded. The history is append only, and a correction is a newer review. Takes exposure_id, the id of a portfolio_book row (not a node_id). An exposure outside the caller team's book answers not_found. Owners and reviewers are member identities and are not served. Paged with limit and offset; the response carries the exact total.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, default 50, maximum 100. | |
| offset | No | Rows to skip, default 0. | |
| exposure_id | Yes | The exposure id, as portfolio_book rows carry it in id. Not a graph node_id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds substantial extra context: append-only history, corrections modeled as newer reviews, the four disposition values, that owners/reviewers are intentionally not served, and the not_found scoping rule. This is real behavior an agent cannot infer from 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?
A single front-loaded paragraph that leads with the resource and ordering before constraints and parameters; dense but every clause carries information. Slightly overlong sentences keep it from a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description enumerates the returned fields (disposition, note, next review date, recorded time) and the total-count behavior, and covers scoping errors and the id-type gotcha. Nothing needed to invoke 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 baseline is 3, but the description reinforces the exposure_id semantics (portfolio_book row id, not node_id) and confirms paging via limit/offset with the exact total in the response, adding meaning beyond the schema text.
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 ('credit review history' of 'one exposure') and a return ordering ('newest first'), which clearly separates it from siblings like portfolio_book and portfolio_reviews_due. An agent can identify exactly what it retrieves without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context: it takes an exposure_id that is a portfolio_book row id (not a node_id), and an exposure outside the caller's team book returns not_found. It does not, however, name an alternative tool or spell out when to prefer a reviews-due listing over per-exposure history.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Company values a data provider the caller's bank licenses stated (North Data), looked up under the bank's own key into its own workspace, with the name, legal form, register and register status, the LEI where stated, the graph node it binds to through a stated identifier, the provider's source page (source_url) and when it was read. Only values read under a licence scope that covers the bank's own systems are served. Filter by node_id or by a German register with its court, for example HRB 12345 Hamburg; page with limit and offset. Looking a company up happens in the Stonewake dashboard.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, default 50, maximum 100. | |
| offset | No | Rows to skip, default 0. | |
| node_id | No | Only values bound to this graph node. | |
| register | No | Only values of this German register, with its court. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely useful non-obvious behavior: results are gated by the bank's licence scope, values are read under the bank's own key into its own workspace, and each row carries a source_url plus a read timestamp for provenance.
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?
Reasonably short overall, but the first sentence is a single sprawling clause chain ('values a data provider the caller's bank licenses stated... looked up under the bank's own key into its own workspace, with the name, legal form...') that is hard to parse and buries the key license-scope constraint mid-paragraph rather than front-loading it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the return-shape burden and it does list the returned fields and provenance metadata. Combined with the licence-scope caveat and filter/paging guidance, an agent has nearly everything needed, with only the sibling boundary left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline would be 3, but the description earns an extra point by giving the register format example ('HRB 12345 Hamburg') that shows the court must be included, and by restating the node_id binding and paging semantics in context, adding meaning beyond the terse schema 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 description states the resource (company data from the North Data provider) and the returned fields (name, legal form, register, LEI, graph node, source_url), and the licensing constraint ('only values read under a licence scope that covers the bank's own systems') implicitly draws a boundary against sibling tools like company_records. However, it never names an alternative, so the agent must infer the boundary itself, and the opening clause is grammatically tangled.
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 explains how to drive the tool (filter by node_id or by German register with court, e.g. 'HRB 12345 Hamburg'; page with limit/offset) and notes lookup happens in the dashboard, but gives no when-to-use vs siblings such as company_records or company_profile, and no exclusions or prerequisites for the licence-scope rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The upward ownership chains of one company, composed across registers and cited hop by hop, with per register coverage notes. Takes node_id, the graph node id from search_companies hits. threshold is the minimum ownership percentage a chain must keep to be followed, default 25; max_depth caps the number of hops, default and maximum 8. Natural person owners are named only in workspaces where person data is switched on; elsewhere a chain reaching an individual terminates there with a stated terminal reason, and params.include_persons says which applied. Hop values are served verbatim from the registers, never synthesized.
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes | The graph node id, as returned by search_companies hits. Not the entity_id of company_profile. | |
| max_depth | No | Maximum hops to walk, default and maximum 8. | |
| threshold | No | Minimum ownership percentage a chain must keep, default 25. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which already declare read-only, idempotent, non-destructive, closed-world), the description discloses genuinely non-obvious behavior: person owners appear only where person data is enabled, chains otherwise terminate with a stated terminal reason, and hop values are served verbatim rather than synthesized. This is exactly the added context annotations cannot carry.
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, then parameters, then conditional behavior, with no filler. The final sentence about include_persons is dense and slightly overloaded, but every sentence 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?
With no output schema, the description does the heavy lifting on return shape: chains cited hop by hop, per-register coverage notes, and terminal reasons. It is nearly complete, only undercut by the dangling include_persons reference that the schema does not back up.
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 node_id, threshold and max_depth semantics are already fully documented in the schema; the description largely restates defaults (25, max 8). It references 'params.include_persons,' which does not exist in the input schema — a minor confusion source that offsets the otherwise solid node_id provenance 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?
The opening sentence gives a specific verb+resource: 'upward ownership chains of one company, composed across registers and cited hop by hop.' An agent knows exactly what it retrieves, though it never names a sibling (company_network, company_profile) to contrast against, so differentiation is implied rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: the description notes node_id comes from search_companies hits and warns it is 'not the entity_id of company_profile,' which is a useful routing hint. However, there is no explicit when-to-use/when-not guidance or a named alternative for retrieving ownership structure instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The monitored book itself: one row per exposure with the team whose book holds it (team_id, team_name), its label, register identifier, entity class (corporate, sovereign_or_public_body, bank, spv or fund, derived from register-stated facts and null when none has been derived yet), desk, current status band, score, completeness, seen_share (the weight share of applicable signals actually observed), explained_share and reachable_share (the observed share of what a connected source can serve, the figure the insufficient floor reads), the top contributing signals with their citation ids, the most recent status change, and the standing credit review (disposition, note, next review date, and whether that date has passed). A sole trader (a natural person's business by its register's evidence) has status sole_trader and no score, coverage, signals or status change: it is never scored. Ordered most severe first (red, amber, then insufficient, not_assessed and sole_trader, then green). Paged with limit and offset; the response carries the exact total. Set include_inactive true to include exposures no longer actively monitored.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, default 50, maximum 100. | |
| offset | No | Rows to skip, default 0. | |
| include_inactive | No | Include exposures no longer actively monitored. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safe read profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial behavior beyond them: the severity ordering rule, the exact special case that sole traders are never scored and carry no signals, paging semantics, and the fact that the response carries the exact total. This is genuine disclosure 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?
Content is front-loaded with the resource identity, then special case, then ordering, then paging. Every sentence carries information the agent needs, and there is no filler. The first sentence is an extremely dense enumeration of return fields, which strains readability and could have been split, but little of it is wasted given the absence of an output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the full burden of the return shape and does so thoroughly: per-row fields, the special-case row shape for sole traders, the sort order, paging, the exact total, and the include_inactive toggle. Nothing an agent needs to call or interpret this tool 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: limit/offset/defaults are already documented in the schema. The description echoes the paging behavior and restates 'include_inactive' semantics ('exposures no longer actively monitored') without adding new meaning such as ordering impact or interaction with the total count.
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 scope: 'The monitored book itself: one row per exposure', and then enumerates exactly what each row carries. An agent can understand this is the exhaustive exposure listing without opening a schema. It does not, however, name or contrast itself against near siblings such as portfolio_overview or deal_book, so differentiation is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: the tool reads as the full book listing, and the only explicit guidance is 'Set include_inactive true to include exposures no longer actively monitored.' There is no when-to-use-this-vs-alternatives statement, so an agent choosing between portfolio_book, portfolio_overview and deal_book gets no routing help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Preview adding a book of companies to the caller team's monitored portfolio. Pass the book as CSV text whose header is identifier_type,identifier plus, optionally, name, currency, limit_amount and drawn_amount; at most 2,000 rows. Every row is matched by its registry identifier alone, where identifier_type is lei, uk_crn, de_register (register type, number and court, for example HRB 275806 München), us_cik or another national register scheme. The name column is echoed back and never used to match. Each row answers its outcome (add, reactivate, in_book, duplicate, ambiguous, unresolved, invalid), a reason, and the matched node_id and register name. Rows are paged with limit and offset in file order; counts and total always cover the whole file, so page on until offset reaches total. Nothing is written, and applying an import happens in the Stonewake dashboard.
| Name | Required | Description | Default |
|---|---|---|---|
| csv | Yes | The book as CSV text, header row first. | |
| limit | No | Page size, default 100, maximum 100. | |
| offset | No | Rows to skip, default 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/idempotent/non-destructive, and the description adds much more: matching is by registry identifier alone, the name column is echoed but never used to match, the full outcome vocabulary (add, reactivate, in_book, duplicate, ambiguous, unresolved, invalid), and that counts/total always span the whole file.
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?
Dense but front-loaded: purpose first, then CSV contract, then matching rule, then per-row output, then paging. No sentence is filler, though the single long block is heavier than strictly 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?
No output schema exists, so the description carries the return burden and does so: each row returns an outcome, reason, matched node_id and register name, plus paging termination guidance ('page on until offset reaches total'). Nothing needed to call or interpret 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?
Well past the 100%-coverage baseline: it specifies the CSV header (identifier_type,identifier plus optional name, currency, limit_amount, drawn_amount), the accepted identifier_type values (lei, uk_crn, de_register with register type/number/court, us_cik, other national schemes), the 2,000-row cap, and how limit/offset page in file order with total covering the whole file.
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+resource: 'Preview adding a book of companies to the caller team's monitored portfolio.' It also implicitly separates itself from the apply path by pointing at the dashboard, so the agent can distinguish preview from any write-side sibling.
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 the context ('preview adding a book') and the exclusion ('Nothing is written, and applying an import happens in the Stonewake dashboard'). It does not name a sibling tool as the alternative, but the dashboard reference makes the when/when-not clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Current health of the monitored portfolio: how many exposures sit in each status band (green, amber, red, insufficient, not_assessed) and how many are sole traders (sole_trader: a natural person's business, never scored, so it has no band and no transitions), the active exposure count, the number of transitions in the last 30 days and how many of them are status changes (an exposure's first assessment is an addition to the book, a transition but not a change), and how many exposures have an overdue credit review. Optionally pass transitions_since (an ISO 8601 date-time) to also list the individual status transitions since that moment, newest first, each with its cause: the signals whose change moved the status, their citation ids, and the register record behind the lead one. Start here for questions like how the book is doing or what changed since a date and why.
| Name | Required | Description | Default |
|---|---|---|---|
| transitions_since | No | Also return status transitions at or after this ISO 8601 date-time, newest first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's job is adding semantics — and it does: the 30-day transition window, the definition of sole_trader (never scored, no band), and the addition-vs-status-change distinction. It stops short of describing result ordering for the aggregates or any size limits on the transitions list.
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 the headline ('Current health of the monitored portfolio') and every clause is load-bearing, including the parentheticals that define sole_trader and status change. It is a dense run-on sentence rather than cleanly separated points, which slightly hurts scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must describe the return payload — and it comprehensively enumerates every aggregate plus the optional transitions detail and their fields. An agent has enough to call this correctly and interpret results.
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 goes further: it clarifies that transitions_since triggers an additional list of individual transitions with their causes, signal citation ids, and the lead register record, and that results come newest first. That adds real meaning beyond the schema's terse description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (current health of the monitored portfolio) and enumerates exactly what it aggregates: status band counts, sole-trader counts, active exposure count, 30-day transitions, and overdue reviews. This is clearly distinguishable from siblings like portfolio_book and portfolio_reviews_due 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?
'Start here for questions like how the book is doing or what changed since a date and why' gives clear usage context and positions it as an entry point. It also explains when to pass transitions_since (to drill into individual transitions), but it never names an alternative sibling or states when NOT to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The credit reviews of the monitored book that need attention today (UTC), the overdue ones, whose standing next review date has passed, and those falling due within window_days (14), today included, each group soonest first. Every row names its exposure, team, company label and node_id, current status band, disposition and next review date. Each group lists at most 50 rows, while overdue_total and due_soon_total count every one; never_reviewed counts the active exposures with no review yet. Exposures no longer actively monitored are never listed. Owners are member identities and are not served.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only/idempotent annotations, the description discloses per-group row caps (50), that totals count every row, the never_reviewed counter semantics, exclusion of no-longer-monitored exposures, and that owners are deliberately not served. These are real behavioral constraints an agent could not infer 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 grouping semantics are front-loaded in the first sentence, and each subsequent sentence adds distinct information (row fields, counts, exclusions). It is information-dense but runs long, with the 'owners not served' note appended somewhat abruptly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden and does so: row fields (exposure, team, company label, node_id, status band, disposition, next review date), group sizes, and aggregate counters. An agent knows both when to call it and what shape to expect.
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 zero input parameters, so the baseline is 4. The description does introduce a window_days value (14) that does not appear in the schema, which usefully documents the fixed horizon, though it is not defined as a caller-settable parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource — the credit reviews of the monitored book needing attention today, overdue ones, and those due within window_days — and scopes it precisely (groups, ordering, exclusions). It clearly separates itself from siblings such as exposure_review_history and portfolio_book by defining exactly what is and is not listed.
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 when-to-use condition is explicit: reviews needing attention today, overdue, or falling due within a 14-day window, in UTC. What it does not do is name an alternative tool for the adjacent cases (e.g. historical review data via exposure_review_history), so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Where to download the PDF documents of one subject, for filing them into a document library such as SharePoint. A deal (the id deal_book serves) has its deal report and committee pack, a counterparty (the registry id company_profile speaks) its counterparty report and pack, a company (a graph node id from search_companies) its company profile. The tool first reads the subject, so an id the key cannot read answers not found, then returns each document's /v1 path. The documents are fetched with the same key, which needs the reports scope. No document is generated by this call.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The deal id as deal_book serves it, or the counterparty or company id written as digits. | |
| subject | Yes | deal, counterparty or company. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the bar is lower, yet the description adds real context: the subject is read first so an unreadable id returns not-found, the fetch requires the reports scope with the same key, and no document is generated. It does not cover rate limits or return volume, keeping it below a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded and each sentence carries information (subject mapping, id sources, auth, no-generation). It is a single dense paragraph with some convoluted phrasing ('the registry id company_profile speaks'), so it is efficient but not maximally readable.
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 2-parameter read tool with full schema coverage and rich annotations, the description covers subject semantics, id provenance, auth scope, and error behavior. Since there is no output schema, it correctly hints at the return shape ('returns each document's /v1 path'), though more detail on the response structure would fully close the gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it maps each subject enum value to the origin of the corresponding id (deal_book id, registry id, graph node id). This goes beyond the schema field descriptions, though it does not document id formatting edge cases.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the concrete output (the /v1 download path for each PDF document of a subject) and enumerates the three subject types with what each yields (deal report+committee pack, counterparty report+pack, company profile). It is clear, though the opening phrase 'Where to download' reads slightly like a URL helper before the 'returns each document's /v1 path' sentence clarifies it and it does not name any sibling 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 the use context (filing documents into a library such as SharePoint) and, usefully, tells the agent where each id comes from (deal_book, company_profile registry id, search_companies graph node). It stops short of naming alternatives or exclusions, so it is clear context without explicit when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Review candidates for the natural persons that public registers link to the companies on the caller's team's book (officers, shareholders, beneficial owners), matched by name and by the list's own aliases against the person designations on the six official sanctions lists (EU Financial Sanctions Files, UK Sanctions List, OFAC SDN, OFAC non SDN, the Swiss sanctions list of SECO and the UN Security Council Consolidated List). A date of birth or nationality both sides state that contradicts removes a candidate. A candidate is review material, never a match, and sets no portfolio status or score; each row names the list, the designation reference, the listed names, the fields that matched (matched_on) and those that narrowed (narrowed_on), a link to the official file, and status open or confirmed (an analyst confirmed it on the dashboard, where decisions are made). The result also carries lists, one entry per list with its reading, Checked or Not checked, the reason where it is not checked, its edition and the time of its last check, lists_not_checked, their count, and persons_compared, the count of register persons that were compared. A list that is switched off or was not checked within the last 48 hours reads Not checked, so an empty page says only that no open or confirmed candidate exists among the register persons compared, and it says nothing while lists_not_checked is above 0. Rejected candidates are not served, and a person whom no connected register links to the book is not compared. Paged with limit (default 50, maximum 100) and offset, with the exact total. Available only in workspaces where person data is switched on; elsewhere it answers not found.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, default 50, maximum 100. | |
| offset | No | Rows to skip, default 0. |
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 adds substantial behavioral context: candidates are review material that set no status or score, DOB/nationality contradictions remove candidates, lists switched off or unchecked within 48 hours read Not checked, and results are meaningless while lists_not_checked > 0. It also discloses the per-row field set (list, designation reference, matched_on, narrowed_on, official file link, open/confirmed status).
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 and nearly every clause carries operational meaning (48-hour freshness rule, empty-page interpretation, availability gating). However, it is delivered as one very long run-on paragraph whose dense sub-clauses (row field enumeration, list metadata) slow parsing; slight trimming or restructuring would help.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fully compensates: it enumerates the returned fields, explains the lists/lists_not_checked/persons_compared structure, defines the open/confirmed and Checked/Not checked semantics, states pagination with exact totals, and accounts for availability failures. Nothing needed to call or interpret 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% and both parameters are documented there, so the schema already carries the meaning. The description restates limit default 50/maximum 100 and offset but adds no new syntax or edge-case semantics beyond 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?
States a precise verb (review) and resource (candidates for natural persons linked to book companies), and names the exact matching basis (name plus list aliases against six named sanctions lists). This is unmistakably distinct from siblings like screening_lookup or entity_risk_profile 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 strong context: available only in workspaces where person data is on, otherwise not found; rejected candidates are not served; a person not linked to the book is not compared. It explains how to read an empty page and when lists read Not checked. It never names an alternative sibling tool, so it stops short of explicit when-to-use-vs-alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
How scores are produced for the caller's team: the live scoring configuration (signal weights, status thresholds, evidence-coverage floor; version null means the built-in desk default is active) together with the team's stored rubric versions, newest first. Use this to interpret the status bands and scores that the portfolio and risk tools return.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a read-only, idempotent, non-destructive operation. The description adds valuable behavioral context by explaining the version null meaning, the ordering of rubric versions (newest first), and the distinction between live configuration and stored versions. This goes beyond what annotations alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with the primary purpose stated upfront and supporting details provided in a compact parenthetical. The second sentence gives a clear usage directive without redundancy. Every sentence contributes meaningful 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?
Given there is no output schema, the description sufficiently enumerates what the tool returns: live scoring configuration (signal weights, status thresholds, evidence-coverage floor, version) and stored rubric versions newest first. It also explains the intended interpretation use case. No critical information is missing for an agent to invoke and understand this tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so there are no parameter semantics to clarify. The description appropriately focuses on the tool's return content instead. This matches the baseline for a no-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it explains how scores are produced for the caller's team by returning the live scoring configuration and stored rubric versions. It identifies specific content elements (signal weights, status thresholds, evidence-coverage floor) and distinguishes itself from sibling tools focused on search, profiles, and portfolio data.
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 tells the agent when to use this tool: to interpret status bands and scores returned by portfolio and risk tools. While it does not name alternative tools or state when not to use it, the provided context is clear enough for an agent to select it appropriately among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Screenings run for the caller's team, covering organizations and countries, and natural persons only in workspaces where person data is switched on (elsewhere a person screening answers not_found and the person filter an empty page); each row names its team (team_id, team_name; both null on a workspace wide screening every team reads). Without screening_id this lists screening runs newest first, filterable by subject_type (entity, country or person), by the subject's ids (node_id for a company from search_companies, entity_id for a registry institution from company_profile, iso3 for a country), or by subject name; paged with limit (default 20, maximum 100) and offset, and the response carries the exact total. With screening_id it returns that one run in full. First comes official_lists, a deterministic comparison of the subject with each official sanctions list it names, made when the run is read and not on the screening day, one status per list (listed only on an identifier the list itself states, name match awaiting review, name match reviewed, no entry found, or not checked with the reason; a name match is never a hit, names match exactly so other spellings are not found, and a list that was not checked never reads as clear). Each entry of an entity, vessel or aircraft carries published_fields, the fields its list publishes on it, verbatim, each with the path where the list states it; the fields that can state a natural person (free text, other parties, contact lines) are served only in workspaces where person data is switched on, elsewhere they are withheld and published_note says so. Then the adverse media verdicts per category with rationale and review state, the drafted summary, grounded findings with their press quotes, and the sources behind them. A person screening returns official_lists and its grounded findings with their sources and nothing else, never a verdict, an assessment, a drafted summary or any score, rating or ranking of the person. Findings quote reported coverage, not established fact.
| Name | Required | Description | Default |
|---|---|---|---|
| iso3 | No | Filter by the screened country's ISO alpha-3 code. | |
| limit | No | Page size, default 20, maximum 100. | |
| offset | No | Rows to skip, default 0. | |
| node_id | No | Filter by the subject's graph node id. | |
| subject | No | Filter by subject name, matched on its normalized form. | |
| entity_id | No | Filter by the subject's registry entity id. | |
| screening_id | No | A screening id from the list; when present the other arguments are not used. | |
| subject_type | No | Filter the list by subject kind. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only, idempotent, non-destructive safety profile, yet the description adds substantial behavioral context: person screenings answer not_found where person data is off, official_lists are computed at read time not screening day, name matches are never hits and exact-match only, unchecked lists never read as clear, person fields are withheld with a published_note, and person results never carry a verdict/score/rating. This is well beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The scope statement is front-loaded, but the body is an unusually dense run-on with nested parentheticals and semicolon-joined clauses that make it hard to parse quickly. Most content earns its place, but the prose could be cut and broken into structured points without losing 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 no output schema, the description carries the return-value burden and does so: it describes official_lists and one status per list, published_fields with their paths, adverse media verdicts with rationale and review state, the drafted summary, grounded findings with press quotes, and sources. For a complex tool with 8 params and no output schema, this is complete enough to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it maps node_id to companies from search_companies, entity_id to registry institutions from company_profile, and iso3 to countries, and clarifies the screening_id precedence rule. It does not add format or syntax detail beyond the schema for the paging parameters, so it is not a full 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?
The description states a precise verb+resource (list screening runs, or return one run in full) and clearly distinguishes the two modes by the presence or absence of screening_id. It also carves out its niche against siblings like sanctions_person_candidates and entity_risk_profile by naming what it covers (official_lists, adverse media verdicts, findings). An agent can identify the tool without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear when-to-use context for each mode: without screening_id it lists runs (with filter options), with screening_id it returns a single run and ignores other args. It also states the person-data prerequisite that governs whether person screenings and person fields are available. It does not explicitly route the agent to named alternatives among siblings, 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.
Find a company by name or identifier. The query can be a scheme-prefixed identifier such as lei:5493001KJTIIGC8Y1R12, a bare registration number (CRN, CIK, LEI and similar shapes), or a company name (matched exact, then prefix, then token, then fuzzy). Hits carry the graph node_id that entity_risk_profile takes, plus jurisdiction, status fields, and register identifiers. connected_sources names the registers an empty result was searched against. In workspaces where person data is switched on, the natural persons the registers name are found too, after every company, with node_type person and score null; they are never scored.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum hits, default 10, maximum 25. | |
| query | Yes | Company name, scheme:value identifier, or bare number. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description is free to add behavior the annotations cannot: the exact→prefix→token→fuzzy match cascade, the fact that connected_sources discloses which registers were searched on an empty result, and that person hits are appended after companies with node_type person and score null and are never scored. That last point in particular prevents a real misreading of the output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then query forms, then return shape and the person-data caveat. Four dense sentences with no filler, though the run-on identifier example and nested clauses make it slightly heavier to parse 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?
With no output schema, the description carries the full burden of describing returns, and it does so: node_id, jurisdiction, status, register identifiers, connected_sources, and the person-entry shape. It does not address result ordering or what to do when the graph node_id is absent, but the coverage is otherwise strong for a two-parameter search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds genuine semantics for the undocumented-by-intent query forms (scheme:value, bare CRN/CIK/LEI, human names) and the fallback matching order the schema cannot express. Only limit is left purely to the schema, which fully covers it with min/max/default.
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 ('Find a company by name or identifier') and immediately distinguishes itself from siblings by naming the downstream consumer, entity_risk_profile, and the node_id handoff. An agent can tell it apart from screening_lookup or company_profile 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 how and when the tool fits: it accepts scheme-prefixed IDs, bare registration numbers, or names, and it explicitly says results feed entity_risk_profile. It does not, however, state when to prefer a sibling lookup (e.g. screening_lookup) or what to do when the connected_sources list is empty.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the Stonewake API documentation at docs.stonewake.ai: authentication and the swk_live_ key format, quickstart, key management, error bodies, status codes, and rate limits. Deterministic text search over the official pages; returns the best matching excerpts with each page's URL. This tool needs no Stonewake API key.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | What to look up, for example: rate limits. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark read-only, idempotent, and non-destructive behavior. The description supplements this with deterministic text search, best-matching excerpts with page URLs, and the no-API-key requirement. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences; each carries content: scope/topics, behavior/output, and auth requirement. No filler, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Single-parameter read-only search with no output schema; the description tells the agent what it searches, what it returns, and that no key is needed. Nothing essential 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?
The only parameter, query, is fully documented in the schema with an example. The description reiterates topic scope but adds no meaning beyond what the schema already provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Search) and resource (Stonewake API documentation), enumerates concrete topics, and clarifies deterministic search with excerpt/URL returns. Unlike sibling tools that search company data, this clearly targets docs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent this tool needs no Stonewake API key, which is a useful usage condition. It does not explicitly name alternatives or exclusions, but the target context is clearly distinguishable from sibling data-search tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Preview a tender portal export for the caller team's own tender notices. Pass the file the portal exported (CSV, XLSX or the XML of one eForms notice, at most 700,000 bytes) base64 encoded in content_base64 and its name in file_name; the extension must match the content. Name the portal the file was exported from in source_portal; uploads from dtvp, vergabe24, dab, dtad, had and vergabe_saarland are not accepted for now. The header is matched against the known portal profiles; when none matches, the answer says mapping_required with the file's columns and the available_fields, and a second call passes mapping, an object from column name to field. Every row answers its outcome (new, update, unchanged, duplicate, skipped, invalid), the reference that identifies it and a reason; unknown columns are listed and never read, and counters name every dropped value. Rows are paged with limit and offset in file order; counts and total cover the whole file. Nothing is written, and confirming an upload happens in the Stonewake dashboard.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, default 100, maximum 100. | |
| offset | No | Rows to skip, default 0. | |
| mapping | No | Optional. Column name of the file to upload field, as available_fields of a preview lists them. | |
| file_name | Yes | The exported file's name, for example treffer.xlsx. | |
| source_portal | Yes | The portal the file was exported from; manual is a file the bank compiled itself. | |
| content_base64 | Yes | The exported file, base64 encoded. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/destructive/idempotent/openWorld, so the safety profile is covered; the description adds real behavioral context on top: 'Nothing is written', per-row outcomes, unknown columns 'never read', counters naming dropped values, and paging/count semantics in file order. It does not detail error behavior for size or extension violations beyond the stated limits.
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 the purpose before constraints, and each sentence carries distinct information (accepted portals, mapping fallback, row outcomes, paging). It is dense with semicolons and somewhat long, but little of it is expendable 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?
With no output schema and a nested mapping object plus a two-call mapping flow, this tool is complex, yet the description covers the return shape (outcomes, reference, reason, counters, mapping_required with columns/available_fields), paging, size/format limits, and the no-write guarantee. Nothing an agent needs to invoke 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 meaning beyond the schema: content_base64 is the raw export file whose extension must match the content, source_portal names the origin portal and manual means bank-compiled, mapping maps column name to field, and limit/offset page rows 'in file order' with counts over the whole file.
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 ('Preview a tender portal export') plus scope ('for the caller team's own tender notices'), which cleanly separates it from sibling import/preview tools like portfolio_import_preview and from tender_matches. An agent can tell what it does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use conditions (pass the portal-exported file, extension must match the content) and when-not (uploads from dtvp, vergabe24, dab, dtad, had, vergabe_saarland are not accepted). It also spells out the fallback workflow: a mapping_required response with columns and available_fields, then a second call with mapping.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The public procurement notices the caller team's tender profiles matched, newest first, one row per procedure citing its newest matching notice. Each match explains every criterion its profile sets (CPV code, NUTS region, value band in EUR, keyword, procedure type, buyer legal type, notice kind, days to the tender deadline) with the outcome hit, the notice field it read, what the notice states there and what the profile asks, and carries the notice itself with its source_url and record_id as the citation. A notice is a match only when it hits every criterion its profile sets, so an unknown is never a match. Winners are never shown, and a buyer whose legal type may name a natural person is withheld (buyer_withheld). Filter by status (new, dismissed or in_deal_book) or profile_id, page with limit and offset, or pass match_id alone to read one match. A match outside the caller team answers not_found. A match can also cite a notice of the team's own portal lane (portal_notice, an export the bank uploaded or an alert of one of its portal accounts), chosen by a profile or by the portal's own saved search (decided_by portal_search). Pass deal_id alone for the matches an analyst took into that deal of the Deal Book (status in_deal_book), where the notice is cited on the deal.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, default 50, maximum 100. | |
| offset | No | Rows to skip, default 0. | |
| status | No | Only matches in this status. | |
| deal_id | No | The matches a deal of the Deal Book holds, by its deal id. | |
| match_id | No | One match by its id, as list rows carry it in id. | |
| profile_id | No | Only matches of this tender profile. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already declare readOnly/idempotent/non-destructive, the description adds substantial behavioral context: a notice matches only when every criterion hits, unknowns are never matches, winners are never shown, buyers naming natural persons are withheld (buyer_withheld), out-of-team matches return not_found, and the portal_notice lane is disclosed.
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 most sentences carry information, but the description is a dense wall of long run-on sentences (e.g. the portal lane and deal_id sentences) that is hard for an agent to parse quickly. Information density is high, yet readability and structure suffer.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the full burden and does so: it describes the returned match structure, the per-criterion explanation fields, source_url/record_id citations, and the portal_notice variant. Nothing an agent needs to interpret results 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 a baseline of 3 applies, but the description adds real meaning: match_id alone reads a single match, deal_id alone scopes to Deal Book matches, and status enumerates new/dismissed/in_deal_book. limit/offset add nothing beyond the schema, keeping it below 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?
The opening sentence names the specific resource and scope: the procurement notices the caller team's tender profiles matched, one row per procedure with newest-first ordering. It distinguishes clearly from siblings like tender_profiles and tender_export_preview by explaining exactly what a returned match is.
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 invocation modes: filter by status or profile_id, page with limit/offset, pass match_id alone to read one match, or pass deal_id alone for Deal Book matches. It doesn't name sibling tools as alternatives, but the selection conditions among its own modes are spelled out clearly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The caller team's live tender profiles by name, each with what it asks of a public procurement notice (CPV codes and NUTS regions with everything below them, a value band in EUR, keywords matched as whole words in the title or description, procedure types, buyer legal types, notice kinds and the minimum days to the tender deadline), its use case (finance_project or bank_as_bidder) and whether it is active. An empty list or a null bound is a criterion the profile does not set. Paged with limit and offset; the response carries the exact total.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, default 50, maximum 100. | |
| offset | No | Rows to skip, default 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the safety burden is lifted; the description adds genuinely new behavior: paging semantics, that the response carries the exact total, and that an empty list or null bound means the profile does not set that criterion. These are non-obvious semantics an agent could not get 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?
Front-loads the resource and its fields, then adds the edge-case semantics and paging in short clauses. It is dense but every clause (CPV/NUTS, value band, keyword whole-word matching, use case) earns its place. The parenthetical is long but informative rather than redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must describe return values, and it does so thoroughly: the criteria fields, the use case enum values, the active flag, and the total. Combined with the edge-case semantics, an agent has everything needed to interpret a 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%, so limit and offset are fully documented (defaults, max) in the schema itself. The description only restates 'paged with limit and offset' and adds the total-count behavior, adding little beyond structured data. Baseline 3 is correct.
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 ('the caller team's live tender profiles') and enumerates the fields each profile carries, so an agent knows exactly what this returns. It does not, however, name or contrast itself with the obvious siblings (tender_matches, tender_export_preview), so sibling differentiation is left to inference from the word 'profiles'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use, when-not-to-use, or alternative routing. The description only says what a profile contains, never why an agent would call this versus tender_matches or tender_export_preview. Usage context is entirely unstated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
deal_duplicatestender_matches1 field changedInput schema / properties / deal_idAdded value: +{
+ "description": "The matches a deal of the Deal Book holds, by its deal id.",
+ "maxLength": 16,
+ "minLength": 1,
+ "pattern": "^[0-9A-Za-z]+$",
+ "type": "string"
+}deal_duplicateslicensed_factscompany_socialreport_downloadscompany_newsaudit_log_exportalert_deliveriesalert_eventscompany_events1 field changedInput schema / properties / node_id / maximumAdded value: +2147483647company_financials1 field changedInput schema / properties / node_id / maximumAdded value: +2147483647company_financing1 field changedInput schema / properties / node_id / maximumAdded value: +2147483647company_network1 field changedInput schema / properties / node_id / maximumAdded value: +2147483647company_overview1 field changedInput schema / properties / node_id / maximumAdded value: +2147483647company_profile1 field changedInput schema / properties / entity_id / maximumAdded value: +2147483647company_public_funding1 field changedInput schema / properties / node_id / maximumAdded value: +2147483647company_records1 field changedInput schema / properties / node_id / maximumAdded value: +2147483647company_regional_context1 field changedInput schema / properties / node_id / maximumAdded value: +2147483647company_sector_context1 field changedInput schema / properties / node_id / maximumAdded value: +2147483647deal_binding_queue1 field changedInput schema / properties / offset / maximumAdded value: +9223372036854776000deal_book1 field changedInput schema / properties / offset / maximumAdded value: +9223372036854776000developments1 field changedInput schema / properties / offset / maximumAdded value: +9223372036854776000entity_risk_profile1 field changedInput schema / properties / node_id / maximumAdded value: +2147483647exposure_review_history2 fields changedInput schema / properties / exposure_id / maximumAdded value: +2147483647Input schema / properties / offset / maximumAdded value: +9223372036854776000ownership_chain1 field changedInput schema / properties / node_id / maximumAdded value: +2147483647portfolio_book1 field changedInput schema / properties / offset / maximumAdded value: +9223372036854776000portfolio_import_preview1 field changedInput schema / properties / offset / maximumAdded value: +9223372036854776000sanctions_person_candidates1 field changedInput schema / properties / offset / maximumAdded value: +9223372036854776000screening_lookup4 fields changedInput schema / properties / entity_id / maximumAdded value: +2147483647Input schema / properties / node_id / maximumAdded value: +2147483647Input schema / properties / offset / maximumAdded value: +9223372036854776000Input schema / properties / screening_id / maximumAdded value: +2147483647tender_export_preview1 field changedInput schema / properties / offset / maximumAdded value: +9223372036854776000tender_matches3 fields changedInput schema / properties / match_id / maximumAdded value: +2147483647Input schema / properties / offset / maximumAdded value: +9223372036854776000Input schema / properties / profile_id / maximumAdded value: +2147483647tender_profiles1 field changedInput schema / properties / offset / maximumAdded value: +9223372036854776000company_public_fundingtender_export_previewtender_matchestender_profilesResearchOracle - 11 financial research tools: 10-K parsing, equity, macro, citation graph.
351 read-only tools: stocks since 1926, options, CDS, bonds, private markets, 13F, macro and crypto
Financial and covenant data for public and private credit: statements, cap stacks, covenants.
Financial market, fundamental, valuation, risk, ownership, forecast, and portfolio tools.
Add one secure layer between your agents and this server.
