DataNewton MCP

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

With no annotations, the description carries the full burden and does well: it discloses billing (preview/validation cost 0, list costs N cards), that continuation is not idempotent and must be replayed with the same token, and that need_structured requires copying draft_*_json from applied_filters. Still missing: error behavior, rate limits, auth, and response shape (e.g. has_payload vs full payload).

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 bulleted layout is front-loaded and most lines carry operational value, but the 'structured_only + leadgen' recommendation is repeated three times and the telegraphic style ('Биллинг: preview/validation=0') makes it harder to parse than necessary. It is dense rather than bloated, but not tight.

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

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

For a 19-parameter tool with no annotations and no output schema, the description covers billing, pagination, and sibling hand-offs, but says nothing about the four JSON request parameters or the market_registry enum values, which are a major part of the tool's surface. Adequate for the NL path, incomplete for the structured path.

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 95%, so the baseline is 3 and the schema already documents most parameters, including the fields-vs-fields_preset priority that the description repeats. The description adds cross-parameter combinations (format + fields_preset + continuation_token) and the continuation/offset incompatibility, but leaves market_registry, company_ops_json, dictionary_query, and misc_request_json without any usage semantics.

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

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

The opening line states the resource (companies/market/segment) and the two input modes (NL question vs structured JSON), and the closing sentence distinguishes it from dn_get_section and dn_get_event. The verb 'ask' is vague and the tool is really a multi-mode router, but an agent can still tell what it is for and where the boundaries with siblings lie.

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 'recipe' block gives concrete when-to-use patterns: preview_only=true for segments over 20 before listing, structured_only + fields_preset=leadgen for paginated lists and card batches, and explicit hand-offs (full section DTO → dn_get_section, market event → dn_get_event). It lacks any explicit 'when not to use' or guidance on the four JSON-mode parameters.

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

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

With no annotations, the description must carry behavioral context. It discloses that the response is lightweight ('без тяжёлых данных') and includes token balance, contract semantics, and example questions, but it does not explicitly confirm read-only behavior, return format, or any limits beyond the lightweight hint.

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

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

The description is a single concise sentence with no wasted words. It is somewhat cryptic due to abbreviations and lacks a clear verb, but it remains compact and 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?

There is no output schema, so the description should explain return values more fully. It lists three kinds of content (token balance, contract, examples) but does not describe their structure or how an agent should interpret them. It is adequate but incomplete for a no-parameter capability endpoint.

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

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

The tool has zero parameters, so parameter semantics are not a concern. The baseline score of 4 applies because there are no parameters to document and the schema is empty.

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 content the tool exposes: remaining MCP tokens, the NL vs structured contract, and example questions without heavy data. However, it does not clearly state that the tool returns capability information, and it does not distinguish itself from siblings like dn_ask or dn_clarify. The purpose is inferable but vague.

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

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

There is no guidance on when to call this tool versus dn_ask, dn_clarify, dn_get_event, or dn_get_section. The phrase 'без тяжёлых данных' hints at a lightweight check, but no explicit usage conditions or alternatives are given.

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

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

With no annotations, the description carries the full behavioral burden and does not say what happens after a pick is submitted, whether the choice is final, what output to expect, or any side effects. It discloses only the trigger and two inputs, leaving the mutation/interaction semantics opaque.

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 very compact and front-loads the trigger condition with no filler. But it reads as a cryptic fragment with unexplained status terms and parentheses, so it is concise at the expense of structural clarity.

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 four-parameter clarification tool with no annotations and no output schema, the description is too sparse. It omits the meaning and effect of the optional parameters, the expected result of submitting a pick, and any behavioral constraints an agent would need to call it safely.

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 only 50%. The description mentions 'session_id' and 'pick', but those are already described in the schema, while the optional 'format' and 'include_payload' parameters remain unexplained in both places. The description therefore does not compensate for the coverage gap.

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

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

The description identifies a clarification step after an 'ambiguous' or 'need_clarification' state, plus the required inputs 'session_id' and 'pick'. However, it never states in plain terms that the tool selects a candidate or resolves ambiguity, so the core action remains only inferable from the schema's 'pick' description.

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 clearly states the trigger conditions: use after an ambiguous company result or a need_clarification segment result, and pass session_id plus pick. It stops short of naming alternatives or when not to use it, but the context for invocation is unusually explicit for a short description.

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

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

No annotations are provided, so the description carries the full behavioral burden. It indicates a single-record card via '(limit=1)' but does not state whether the operation is read-only, what permissions are required, what errors may occur, or what the response looks like.

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

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

The description is a single front-loaded sentence with little waste. However, vague phrasing such as 'и т.д.' and the cryptic '(limit=1)' reduce precision rather than earn their place.

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

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

With no annotations and no output schema, the description should explain required registry/filter usage and return behavior. It only gives a high-level card definition, leaving important operational details absent.

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

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

The schema already documents registry values and filter_json examples at 67% coverage. The description maps loosely to registry categories ('дело СОЮ/арбитража, контракт, лизинг') but adds no guidance for the format parameter or how to construct filter_json.

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

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

The description identifies a specific resource, the market event card, and gives examples such as a court/arbitration case, contract, and lease. It is clear what the tool retrieves, though it does not distinguish its purpose from the sibling dn_get_section.

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

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

There is no explicit guidance on when to use this tool versus dn_ask, dn_capabilities, dn_clarify, or dn_get_section. The '(limit=1)' note implies single-record lookup but does not explain required inputs or selection context.

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

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

No annotations exist, so the description carries the full burden and does little: 'полным payload' hints at a heavy response but says nothing about pagination (limit/offset in params), required identifiers, or permissions. A read-only assumption is only inferable from 'get'.

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 sentence with no waste, though it is arguably too terse for a 5-parameter tool with nested objects.

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 5 parameters, a nested params object, no annotations, and no output schema, the description is far too thin to call the tool reliably. It omits identifier selection, format behavior, and what the full payload contains.

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 only 40%, so the description should compensate, but it mentions only 'section' and adds no meaning for inn/ogrn/format/params. The distinction between looking up by INN vs OGRN, and what 'structured_only' format means, is left entirely undocumented.

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

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

The description names a specific resource ('одна секция карточки компании') and the retrieval verb, and distinguishes itself from dn_ask by noting it returns the full payload rather than an answer. It stops short of 5 because the term 'секция' is only clarified by the schema, not the prose.

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

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

It gives a concrete usage condition: call this after dn_ask when has_payload is present. That is real routing guidance an agent can act on, though it does not state when NOT to use it or contrast with dn_get_event.

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