Magist

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

Explains the otherwise puzzling readOnlyHint=false: the call 'creates or refreshes an idempotent public report URL for the receipt, retained for up to 90 days,' which matches idempotentHint=true and destructiveHint=false. It also discloses determinism ('same inputs always produce the same output, with no LLM in the path') and a legal caveat, adding substantial context 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?

Front-loads purpose and outputs before side effects and the disclaimer, and each sentence carries information. The closing legal caveat is slightly verbose across two sentences but is genuinely relevant to correct reliance on the result.

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 return values and does so thoroughly (regulations and Controls triggered, numeric complexity score, blocker count, cohort breakdown), plus the report-URL side effect and determinism guarantee. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, including the closed-catalog constraint and the audience enum. The description restates the input categories (features, markets, age bands, optional business model) but adds no syntax or format detail beyond the schema, 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 verb and resource ('Run Magist's deterministic compliance engine over a product description') and enumerates the outputs: regulations/Controls, complexity tier, blocker count, cohort breakdown. An agent can distinguish it from lookup/search siblings because this tool computes derived requirements rather than retrieving existing 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?

Gives situational context (research purposes, not a legal determination, consult counsel) and points to list_feature_catalog for valid ids via the schema. However it never states when to prefer this over alternatives like lookup_regulation or search_regulations, so routing 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.

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds real behavioral context beyond that: what the output contains (priority signal tiers and a work summary) and a caveat that results are research mappings rather than a product-specific determination, which sets expectations about the answer's authority.

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, front-loaded with the action and its input, followed by the return shape and a caveat. No redundancy, and the priority-tier enumeration is the kind of detail an agent cannot get from structured fields (there is no 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?

For a single-parameter, read-only lookup with no output schema, the description supplies the missing return-value semantics (priority tiers, summary), the caveat about interpretation, and confirms scope. Nothing an agent needs to call it correctly is 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?

Schema description coverage is 100% and the single parameter documents its format, example ('coppa'), pattern and length. The description only restates the parameter's role ('Given a regulation id') without adding lookup syntax, accepted id source, or error behavior, so the baseline 3 applies.

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

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

States a specific verb and resource ('return the compliance Controls that may satisfy [a regulation id]') and enumerates the returned payload fields (priority signal values, short summary). The scoping sentence ('research information about typical control mappings, not a determination that a given product needs them') implicitly separates it from the requirements/determination sibling, so an agent can tell what this is not.

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 only implied through the framing 'Given a regulation id', which signals when the tool is callable but not when it should be preferred over siblings like lookup_regulation or compute_requirements. No explicit when-not-to-use or alternative routing is provided; 'Consult counsel for scoping' is legal advice, not tool 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 read-only, idempotent, non-destructive, closed-world behavior. The description adds substantive context beyond that: the results are an editorial/firm-claimed directory, inclusion is not endorsement, and bar status plus conflicts must be verified independently — useful trust-boundary information for an agent relaying results.

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 action and filters, followed by a short caveat. Every clause earns its place with no redundancy.

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, but the description characterises the return qualitatively (directory listing of firms) and the annotations cover the safety profile. For a low-complexity read-only search, this is nearly complete; return shape and pagination are 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 jurisdiction resolution, sub-jurisdiction matching, and the forward-compatibility caveat for 'language'. The description adds no parameter detail beyond mentioning jurisdiction and practice area, 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 verb and resource — 'Search Magist's open counsel directory for law firms' — plus the filter dimensions (jurisdiction, practice area). This clearly distinguishes it from siblings like find_vendors and find_controls, which target different directories.

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 frames the intent ('help a user identify licensed attorneys to consult') but names no alternatives and gives no explicit when-to-use/when-not conditions relative to sibling lookup tools. Usage is implied rather than guided.

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 closed-world, so the safety profile is covered. The description adds genuinely non-structured context: what the result contains (vendors, in-house approaches, effort/cost signals, source disclosure) and the editorial neutrality policy ('does not accept payment', 'does not rank or endorse'). It stops short of 5 only because return formatting/pagination is unaddressed.

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 tightly written sentences: the operation and its scope come first, the payload description second, and the trust/neutrality caveat last. No sentence is filler and nothing is buried.

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 takes on the burden of saying what comes back, and annotations handle the safety profile. The only unaddressed items are the optional jurisdiction filter's effect and result volume/pagination, which are minor for a catalog lookup.

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%, with controlId format and jurisdiction semantics fully documented in the schema, so the baseline is 3. The description only restates the controlId precondition and never mentions the jurisdiction filter or how region matching behaves, adding no meaning beyond the schema.

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

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

The description gives a specific verb and resource ('list third-party vendors and in-house approaches') scoped by a Control id, and it even characterizes the payload ('effort/cost signals and a source-disclosure'). It does not differentiate itself from siblings like find_controls or find_counsel, which also operate on the compliance catalog, 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?

Usage is only implied via the input precondition ('Given a Control id') and the framing sentence 'Returns a neutral catalog for research; evaluate fit independently.' There is no explicit when-to-use vs. when-not, and no alternative tool (e.g. find_controls for discovering the controlId first) is named.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered; the description goes beyond that by disclosing payload shape (penalty, authority, primary-source link, practitionerAnalysis) and the important null semantics of penaltyAmount with its listed causes. It omits pagination/ordering behavior and the default sort, which would have made this 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?

Front-loaded with the core action and filters, then the response contents; every sentence carries information. The closing 'historical facts... informational context, not a prediction about a specific product' partially repeats the earlier disclaimer about practitionerAnalysis, costing a little efficiency.

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 carry return-value meaning, and it does: it enumerates the returned fields and explains the null-penalty case. What is missing is volume/ordering behavior (limit defaults are only in the schema) and any hint about response size or how actions are sorted, but the 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 description coverage is 100%, so limit, since, and regulationId are already fully documented with bounds, patterns, and format. The description only restates the two filter parameters and says nothing new about limit or default values, 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 verb and resource ('Return recent regulatory enforcement actions from Magist's catalog') plus the two optional filters, so the agent knows exactly what this fetch returns. It does not name or contrast any sibling (e.g. lookup_regulation vs search_regulations), so it stops short of full sibling differentiation.

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 by the filtering language ('optionally filtered by regulation id and a since-date'), which tells the agent it is a browsable, filterable list endpoint. There is no explicit when-to-use statement, no stated alternative when the agent wants a single action's detail, and no 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds traits they cannot express: deterministic/reproducible output, failure behavior for invalid ids, and a framing caveat that this is reference data rather than a regulatory determination.

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

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

Two sentences, front-loaded with what is returned and who consumes it, followed by the how-to-use constraint. No filler; the em-dash clause and the determinism caveat each add distinct information.

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

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

With no input parameters and no output schema, the description carries full burden and discharges it: it says what comes back (ids plus labels), how to use it, what happens on invalid input, and how to interpret the result. Nothing needed to call it correctly is missing.

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

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

Zero parameters, so the baseline is 4. The description still usefully characterizes what the returned identifiers are (closed catalogs of valid feature/market ids with short labels) and where they are consumed, which is as much parameter-adjacent meaning as a no-arg tool can carry.

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 (return the closed catalogs of valid feature ids and market ids) and immediately anchors them as 'the exact identifiers compute_requirements accepts as features and markets'. An agent can distinguish this from lookup/search siblings 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 an explicit workflow instruction: validate ids here before calling compute_requirements, and explains the consequence of skipping it (ids outside the catalogs are rejected with an actionable error). The alternative tool and the condition that selects it are both named.

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

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

Annotations already declare readOnly=true, idempotent=true, openWorld=false, destructive=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: it discloses the shape of the returned research record and an important scope constraint (factual lookup only, no applicability determination), which sets correct expectations for the caller.

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, front-loaded with the verb, resource, and return contents, followed by the scope disclaimer. Every sentence carries distinct information — no restatement of the title, 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?

There is no output schema, so the description must describe the return value, and it does so thoroughly (the enumerated fields including Controls). Combined with the read-only annotations and the fully documented id 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?

Schema coverage is 100% and the single id parameter already documents the Magist id format, examples, and the pointer to search_regulations for discovery. The description only restates 'by its Magist id', adding no syntax or format detail beyond the schema, 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?

States a specific verb and resource ('Look up one regulation by its Magist id') with explicit singular scope, which separates it from the multi-item search_regulations sibling, and enumerates what the result contains (title, citation, jurisdiction, status, review dates, summary, Controls). An agent can tell exactly what this tool returns 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?

The description draws a clear boundary: it 'returns facts about what a regulation says, not a determination of how it applies to a specific product,' and directs situation-specific questions to counsel. That implicitly routes the agent away from applicability work (compute_requirements) and toward find_counsel, though neither sibling is named explicitly.

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, so the bar is lower; the description adds determinism, pagination behavior, and the citation-URL return shape. It still omits result-count limits or empty-result behavior, 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?

Four tight sentences, front-loaded with the core action and filters before the return/behavioral clauses. No filler, though the determinism sentence is somewhat marginal given the idempotentHint annotation.

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 covers return shape (paginated list with permanent citation URLs). The only gap is guidance against the closest sibling, lookup_regulation, which an agent facing both tools would need.

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 every parameter including defaults and enums. The description's filter list adds consolidation but no new syntax or format detail beyond the schema, 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 (search) and resource (Magist's regulation corpus) and enumerates the filter dimensions, so the scope is unambiguous. It does not explicitly distinguish itself from the sibling lookup_regulation, which likely retrieves a single known regulation, 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 closing sentence gives a clear when-not ('discovery, not a determination of which regulations apply to a specific product'), which implicitly routes determination-style questions to compute_requirements. It does not name any sibling outright or state prerequisites, so it is strong context without full alternative routing.

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

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

Annotations already cover read-only, idempotent, non-destructive semantics, so the bar is lower, yet the description still adds the prerequisite that signing is an opt-in server setting and enumerates the exact failure modes (missing, malformed, unsigned, signature failure) that yield valid:false. It stops short of describing the success payload shape or any rate/auth considerations, so it is strong but not exhaustive.

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 action, then prerequisites, then the negative scope, then error behavior. Dense but every clause carries information; the only cost is that the middle sentence packs several constraints into one long clause chain.

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 carry return semantics, and it does by explaining the valid:false plus reason outcome and when that is expected rather than an error. For a single-parameter verification tool with a nested token object, 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 already 100% and the nested groundingProof fields are documented in the schema, so the baseline is 3. The description pushes past the baseline by constraining usage — the object must be passed back exactly as received and unmodified — which is a real semantic constraint the schema alone does not state.

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 ('Verify a Magist grounding-proof token') and immediately scopes it to the 'groundingProof' field on regulation/control records, which no sibling tool touches. The purpose is unmistakable versus lookup_regulation or search_regulations.

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 says where the token comes from (GET /api/v1/regulations/{id} or /api/v1/controls/{id} with signing enabled) and explicitly warns that MCP tool responses do not carry these tokens, which prevents a whole class of misuse. It also states the boundary condition — it does NOT verify legal correctness or obligation applicability.

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