ADITUS Developer Portal MCP

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 genuinely useful behavioral detail: large response bodies are truncated, with full text only on the docs page — a real trait an agent cannot infer from annotations or schema.

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

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

A single dense sentence, front-loaded with what is returned, with the truncation caveat and input-format note tightly parenthesized. No 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, the description carries the burden of describing the return payload, and it does so by enumerating contract sections plus truncation behavior. It does not describe the envelope/format of the response, a minor 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?

Only one parameter, and schema coverage is 100% with the id-vs-METHOD/path format already documented in the schema description. The description's mention of the id origin adds marginal value, so the baseline 3 applies.

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

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

The description gives a specific verb+resource (fetches the full contract of one endpoint) and enumerates exactly what that contract contains: method, URL, auth, parameters, body example, responses. It is clearly distinct from list_endpoints/search_docs, though it stops short of naming those siblings explicitly.

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 where the required input comes from ('the endpoint id from search/list, or METHOD /path'), which implies the search-then-fetch workflow. There is no explicit when-not or list of alternatives, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds that the payload is Markdown and that supplying a section narrows the response, which is modest but real extra context.

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

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

Three tight sentences with the resource stated first and the guide taxonomy and section behavior following. Dense but every clause carries information; no filler.

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

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

The tool has no output schema, and the description compensates by stating the return format is Markdown and that output can be narrowed by section. Both parameters are addressed, so an agent has enough to call it correctly.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds meaning beyond the schema: it defines the special 'micro-frontend' contract contents and explains that module guides like 'guidelines'/'webhooks' are sourced from the API reference, plus that a section heading (or slug) returns only that part.

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 (an integration guide returned as Markdown) and enumerates the guide families it serves, so an agent can tell it apart from list_endpoints/search_docs. It stops short of explicitly naming which sibling to use instead, so it is clear but not fully differentiated.

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?

Implies usage by explaining what 'micro-frontend' versus module guides such as 'guidelines'/'webhooks' contain, which helps an agent pick the right guide id. However it never states when to prefer this tool over search_docs or get_endpoint, and gives no exclusions or prerequisites.

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

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

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so the safety profile is covered. The description adds value beyond that by enumerating the returned fields, which matters because there is no output schema. It omits pagination/volume behavior, keeping it short of 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?

One compact sentence covering scope and return shape, followed by a short routing directive. Front-loaded, no filler, every clause earns its 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?

For a one-parameter read tool with no output schema, the description plus annotations cover what the agent needs: what it lists, what comes back, and where the id comes from. Only the absence of any note on result size or pagination leaves a small 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% and the schema itself gives the meaning and an example ('ticket-purchase-registration'), so the baseline of 3 applies. The description adds only the source of the id (list_modules), a minor supplement rather than new 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?

States a specific verb (list) and resource (endpoints) scoped to 'one module', and enumerates the returned fields (id, method, path, sub-group, summary). This distinguishes it cleanly from list_modules and the singular get_endpoint without opening either schema.

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

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

Gives an explicit prerequisite and provenance for the argument: 'Use the module id from list_modules.' That is real routing guidance. It stops short of stating when to prefer this over get_endpoint or search_docs, so it is clear context rather than full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds genuine domain context beyond that, explaining the semantics of the 'direction' field (inbound vs outbound) and mentioning that documentation URLs and integration guides are included.

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 delivers the core content, with the module fields listed first and the integration-guide addendum second. It is efficient, though the parenthetical definition of direction makes it slightly long for one sentence.

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

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

With no output schema and no parameters, the description carries the burden of explaining the return shape and does so adequately: modules with direction, endpoint counts, doc URLs, plus integration guides. It is complete enough to call correctly, missing only explicit sibling routing.

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 has zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No parameter information is expected or missing.

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 ('All top-level ADITUS API modules') and enumerates the returned fields (direction, endpoint counts, documentation URLs, integration guides). It is clear what the tool does, but it does not explicitly differentiate itself from siblings like list_endpoints or get_endpoint.

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 as a discovery/entry-point call ('top-level modules', 'also lists the integration guides'), but there is no explicit when-to-use or when-not-to-use guidance, and no alternative sibling is named for the cases where the agent should instead drill into endpoints or guides.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond them by disclosing the result shape (ranked hits with ids) and the fields searched, which matters since no output schema exists.

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

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

Two tight sentences, front-loaded with the search scope before the workflow hint. Every clause carries information; nothing is redundant with the schema or annotations.

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

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

With no output schema, the description compensates well by describing the return (ranked hits with reusable ids) and the searchable surface. Minor gaps remain around result ordering/pagination behavior and empty-result handling, but an agent has enough to invoke it correctly.

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

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

Schema description coverage is 100%: 'query' carries the search-term semantics and examples, and 'limit' documents its default and bounds. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb (full-text search) and the exact resources covered (API modules, endpoints by name/path/description, and integration guides), naming guide types explicitly. This clearly distinguishes it from the sibling get_endpoint/get_guide, which fetch by id rather than search.

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 establishes the search-then-fetch workflow by stating the hits carry ids 'usable in get_endpoint / get_guide', which tells the agent when to reach for this tool first. It stops short of explicitly contrasting with list_endpoints/list_modules or stating when search is a poor choice.

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