Maplith

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

It reveals behaviors not in annotations: determinism, no upload/storage/spend, first map free, no card/subscription, and metadata-only processing. All of this is consistent with readOnlyHint=true.

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

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

The main purpose is front-loaded in a clear first sentence. There is slight noise from '(issue #36)' and the promotional pricing sentence, but the text remains compact and 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 one-parameter read-only estimate tool with no output schema, the description covers input format, expected output (DKK list price and map contents), and key caveats (free first map, nothing stored/spent). No significant gap remains.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds 'FILE METADATA only' and 'never contents', reinforcing that files entries are metadata descriptors (path/bytes), not actual content. This is helpful 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?

The description states a concrete function: submit file metadata and receive a DKK list price for a scan plus map contents. This clearly distinguishes it from sibling fetch/get/route/list tools, which are about retrieving or listing data rather than estimating cost.

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 signals the use case: 'for mapping a company's own systems' and 'Free, instant, deterministic list price' with metadata-only input. It does not explicitly name alternatives or exclusions, so it misses a 5, but the context is unambiguous.

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

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

The annotations already mark this as read-only and non-open-world; the description adds the return field set (id, title, text, url, metadata) and notes the output shape is tailored for ChatGPT connectors. It does not discuss error behavior for invalid ids, but for a simple one-document read this is a minor gap.

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 dense sentences cover purpose, id format, return shape, and the main alternative without filler. The most important invocation detail (search-result id format) 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?

For a simple read-only fetch with one fully-documented parameter and no output schema, the description gives enough to call it correctly: what the id means, what comes back, and how it differs from structured siblings. No critical information is missing for a well-scoped single-document retrieval.

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 single id parameter is fully described in the schema, and the description repeats that exact guidance without adding constraints, default behavior, or examples beyond the same prefix list. With 100% schema coverage, this meets the baseline but provides no additional 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 states a specific action and resource, 'Fetch one document from the map', and defines the id format with concrete prefixes. It also names the structured get_object/get_process/get_metric siblings, so an agent can distinguish this flattened fetch from those alternatives.

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 usage context is given: use the id from a search result, and clients able to call get_object, get_process, or get_metric can get the same data with structure. It does not explicitly specify when one should choose fetch over those tools beyond the 'connectors expect' shape, so it stops just 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.

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses important runtime behavior: for large maps, truncated becomes true and truncated_note indicates counts may be lower bounds. This is valuable context that annotations do not provide and helps the agent interpret results correctly.

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, each serving a purpose: the first describes content and usage, the second covers a specific edge-case behavior. Information is front-loaded with the overview, then the truncation note. 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 parameters and no output schema, the description fully covers what the agent needs: what data is returned, when to use it, and how to interpret truncation. It is complete for an orientation 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?

The tool has zero parameters, so the description has no parameter burden. The baseline of 4 is appropriate since the schema is empty and no parameter semantics are needed.

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 provides an overview of the workspace's data map, enumerating specific content (domains, business objects, relation/finding counts, last built time). This distinguishes it from sibling tools like get_object or list_findings, which are more granular. The 'Call this first' phrase reinforces its role as an entry point.

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 instructs the agent to call this tool first for orientation, giving a clear when-to-use directive. It does not name alternatives or explicitly state when not to use it, but the context is strong enough that this is a minor gap.

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=true, so the read-only nature is covered. The description adds valuable context: caveats reveal when the metric cannot be trusted and the output includes exact object.field grounding. 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?

Two sentences, no filler, and the most important usage warning is front-loaded. Every phrase earns its place, and the structure is easy for an agent to parse quickly.

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 by explicitly listing the output contents: formula, exact grounding, and caveats. It also tells the agent when to consume those caveats. For a one-parameter lookup tool, this is complete and 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%, with the only parameter 'name' described as 'Metric name from list_metrics'. The description adds no additional parameter-level detail, but the baseline of 3 applies because the schema already fully documents the 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 clearly states what the tool does: returns the full definition of one metric, including formula, object.field grounding, and caveats. It distinguishes from list_metrics by focusing on a single metric's full definition, though it does not explicitly name sibling alternatives.

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

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

It gives a clear context for use: read the caveats before computing or citing the number. This implies the tool should be used when a metric's precise definition or trustworthiness matters. It does not explicitly list when not to use it or compare it with alternatives, but the guidance is still actionable.

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=true, so the tool's safety profile is known. The description adds meaningful behavioral context by warning that pii=true fields identify people and must not be selected or echoed unless explicitly required, and by clarifying row coverage semantics in relations. This exceeds 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?

Two sentences front-load the full scope of the tool and then add a critical PII constraint. Every phrase contributes substance — object components, relation details, and an operational safety rule — with no filler or repetition.

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 by thoroughly enumerating what is returned: agent-oriented description, fields with explicit pii flags, source systems, every relation with strength/join key/row coverage, and mentioning findings. The PII warning closes a key operational gap. For a single-object read tool, this is complete.

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 already provides 100% description coverage for the only required parameter, 'name', including case-matching behavior. The tool description adds no additional parameter-level meaning beyond the schema, so the baseline of 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 opens with a specific verb and resource ('Full detail for one business object') and enumerates the exact payload: description, PII-flagged fields, source systems, relations, and findings. This clearly differentiates it from siblings like get_metric or get_process, even without naming them.

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 when to use this tool through 'Full detail for one business object', letting an agent infer it is the depth-first object lookup. However, it never names alternatives such as get_map_overview or states when not to use it, so guidance remains implicit rather than explicit.

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

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

Annotations establish readOnlyHint=true, and the description adds useful behavioral detail: it discloses the return content (happy path step counts, median hours, deviating variants with missing/extra steps) and hints that deviations are candidate findings. This goes beyond the annotation without contradicting it.

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 that immediately states scope ('Full process detail for one object type') followed by specific output elements. There is no filler, repetition, or unneeded detail.

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 tool with no output schema, the description conveys the key return elements and their meaning (happy path, deviating variants, findings candidates). It does not spell out the exact response shape or how to handle large variant sets, but that is a minor gap for such a simple interface.

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 sole parameter object_type already has a clear description with an example ('order'). The tool description reinforces 'one object type' but does not add new parameter syntax or format details, 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?

The description clearly identifies the tool as returning detailed process information for one object type, with specific content (step counts, median times, deviating variants). It distinguishes from the sibling list_processes by emphasizing 'one object type' and 'Full process detail', though it does not explicitly differentiate against get_object or get_metric.

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 phrase 'for one object type' implies this is the detailed single-process counterpart to listing processes, giving some usage context. However, there is no explicit guidance on when to choose get_process over siblings like get_object or list_processes, nor any 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?

Even with readOnlyHint=true, the description adds substantial behavioral insight beyond the annotation: it is metadata-only, the named finding is always included when visible, other findings are a relevance selection, and truncation is surfaced via fields 'truncated' and 'truncated_note.' No contradiction with annotations 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?

The description is long, but the length is largely earned: it enumerates many distinct return components and provides workflow and truncation guidance. The main structural weakness is that the longest sentence is a dense list without line breaks, which makes it harder to scan quickly, though it remains front-loaded and purposeful.

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?

Because there is no output schema, the description carries the full burden of explaining the return payload, and it does so thoroughly: signal, repair steps, objects/PII, join paths, process/step, findings, metrics, historical context, and trust warnings. It also covers the truncation edge case and the metadata boundary, so an agent unfamiliar with the system can 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?

The single parameter is fully described in the schema as 'The id of a signal from list_signals,' and the description reinforces that connection by telling the agent to start from list_signals. Since schema description coverage is 100%, the description adds little beyond what the schema already provides, so the baseline score 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?

The description states a specific verb and resource: it returns the full task context for a single signal in one callches. It enumerates the exact content categories, which clearly differentiates it from sibling tools like get_object or get_metric, and grounds it in a workflow starting from list_signals.

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 workflow guidance: 'Start from list_signals, then call this for the signal you mean to work on.' It also states the boundary of the tool, warning that it is metadata and that actual rows must be fetched 'using the routes,' which tells the agent when not to rely on this call as the final data source.

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 only provide readOnlyHint=true and openWorldHint=false. The description adds meaningful behavior beyond that: mentions truncation possible with truncated/truncated_note fields, finding_key stability across rescans, and that ids are per-run. These are important for agent correctness and go beyond the structured 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, front-loaded with the main purpose, then filter, then key behavioral caveats (stable key, truncation). No filler. Each sentence adds value.

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, so the description must cover return shape. It mentions the map, truncation/truncated_note, and finding_key, which are the main things an agent needs to interpret results. It does not describe other finding fields (evidence, recommendation), but those are named in the first sentence. For a simple list tool with one optional filter, this is nearly complete; slight gap is not describing the returned finding object's other fields.

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 0%, so the description must compensate. The status parameter is fully an enum with 4 values in the schema, but description only says 'optionally filter by status' with no detail; however, with 0% coverage, the description at least confirms the filtering behavior. It does not enumerate the status values, but the schema already does, so the description adds the optionality 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?

Description states a specific verb+resource ('List findings'), clarifies what findings are in this tool's context (cross-system discrepancies with evidence, recommendation, lifecycle status), and the siblings list contains other list_* tools but the description's detail about 'documented findings for this workspace' and stable finding_key distinguishes it without needing sibling inspection.

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 context (findings for this workspace, filtered by status) but does not explicitly say when to use this tool versus siblings like get_map_overview, list_signals, or search. There is no when-not-to-use guidance or alternative tool naming.

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?

Even with annotations already declaring readOnlyHint=true and openWorldHint=false, the description adds valuable behavioral detail: metrics are verified against map fields, caveats are inherited, and results may be truncated with truncated and truncated_note set. It also states that unsupported numbers simply do not exist, which meaningfully shapes agent expectations.

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 compact and front-loaded with the core purpose, and each sentence adds information about grounding, caveats, or truncation. It is slightly dense and jargon-heavy, but it earns its length and contains 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?

For a zero-parameter, read-only tool with no output schema, the description covers the essential behavioral contract: what metrics are, what caveats to expect, and how truncation is signaled. It does not detail the shape of each returned metric, but the truncation semantics and grounding guarantees provide enough context for an agent 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?

The tool has zero parameters and schema coverage is 100%, so there are no parameter semantics to clarify. Per the baseline for zero-parameter tools, the description does not need to compensate, and it does not introduce any misleading parameter-related claims.

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 identifies the tool as returning workspace-level KPI metrics that are grounded in map fields, and the phrase 'the list is cut' confirms it produces a list. It does not explicitly state a verb like 'list all metrics' and does not contrast itself with sibling get_metric, 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?

The description implies the tool is for retrieving metrics, but it gives no explicit guidance on when to use list_metrics versus get_metric, list_findings, list_processes, or list_signals. No alternatives, exclusions, or selection conditions are mentioned, so an agent must infer the appropriate use case.

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=true, and the description adds valuable behavioral context: processes are 'discovered deterministically', and truncation is disclosed ('truncated is true and truncated_note explains'). This goes beyond the annotations without contradicting them, making the tool's behavior predictable.

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

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

The description is two sentences, front-loaded with the core purpose and immediately differentiating from get_process. The truncation note is placed at the end, which is logical, and there is no redundant or filler text. Every sentence 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?

Given the absence of an output schema, the description adequately conveys what the tool returns (case count, happy-path share) and the truncation mechanism. It also references get_process for full flow. While it does not specify the exact JSON structure, the described fields are sufficient for an agent to understand the result. Minor gap: the meaning of 'happy-path share' is not elaborated, but it is likely self-explanatory in context.

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 the schema trivially covers everything. The description adds no parameter-specific details, but none are needed. According to the rubric, a zero-parameter tool receives a baseline of 4, and there is no gap to compensate for.

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 what the tool does: it lists processes derived from an object-centric event log, one per central object type, with case count and happy-path share. It also explicitly contrasts with get_process ('Use get_process for the full flow'), distinguishing it from a key sibling. The purpose is specific and 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 gives a clear pointer to an alternative: 'Use get_process for the full flow', implying this tool is for a summary/list rather than full detail. It also discloses truncation behavior. However, it does not explicitly state when to use this tool over other list siblings like list_metrics or list_findings, though the context of processes is implicit.

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

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

Annotations already mark the operation as read-only, and the description adds useful behavioral context: signals are typed events with severity, payloads are aggregates rather than rows, and pagination uses a returned next_cursor. It also hints at polling semantics, which is valuable beyond the readOnlyHint.

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 yet information-dense, front-loading the core concept, then giving examples, filters, pagination, payload semantics, and follow-up tools. Every sentence earns its place, with no redundant restating of the title or 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 tool with five optional parameters and no output schema, the description covers the signal shape, filtering options, pagination, payload nature, and follow-up routes. It does not detail the exact return fields or severity values, but the description is complete enough for an agent to invoke the tool 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 80% with detailed descriptions for limit, since, cursor, and unacted. The description adds some context, such as since being 'an ISO timestamp from a previous call' and using 'the returned next_cursor,' but it does not substantially expand on the kinds parameter or the exact filtering semantics beyond what the schema already provides.

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 identifies the resource as 'signals' and the operation as polling ('poll it to find work'), framing it as a list of map changes. It distinguishes the tool from siblings by positioning it as the 'pulse' versus re-reading the whole map, and by routing follow-ups to list_findings, get_object, and route.

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 guidance: poll this tool to discover changed work rather than re-reading the entire map. It also explains follow-up usage with list_findings, get_object, and route, though it does not explicitly enumerate when NOT to use this tool or name a direct alternative.

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 readOnlyHint=true already declared, the description goes well beyond annotations by disclosing the return semantics: executable join_specs, null when a hop can't be tested, cardinality and verb direction, strength, measured row coverage including blank-key misses, caveats, object systems, and PII fields. It also clarifies that the map never returns data itself.

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

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

The description is long and dense, but every clause earns its place because there is no output schema to document the returned fields. The core outcome is front-loaded, followed by specifics and usage guidance, though the single run-on sentence structure is heavier than ideal.

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 tool with two parameters and no output schema, the description is unusually complete: it enumerates the return payload, defines ambiguous terms like row coverage and null hops, notes PII exposure, and gives invocation timing. Nothing essential to calling the 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?

The schema already documents both parameters at 100% coverage with examples, which sets the baseline at 3. The description adds meaningful behavior beyond the schema: object names are matched in any case, start vs. target direction matters, and output spelling uses the map's own naming.

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 and resource: given start and target objects, it returns the shortest verified join path. It clearly distinguishes route from sibling data-fetching tools by framing it as cross-system navigation (the map as GPS) rather than data retrieval.

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 says to use the tool before fetching data in the human's own systems and explains what it provides: where to look, by which columns, and how much to trust each step. It does not name sibling alternatives or state when not to use it, but the usage context is clear.

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 only declare readOnlyHint=true; the description adds case-insensitive matching, snippet returns, counts per kind, result id/title/url, the 50-document limit, and truncation semantics. This goes well beyond the structured data and fully discloses behavior.

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

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

The description is long but every sentence earns its place: purpose, exclusions, return details, limits, and truncation are all relevant. It is front-loaded with scope and exclusions, making it easy to scan.

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

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

For a search tool with one parameter, no output schema, and a read-only annotation, the description covers return format, count semantics, limit, truncation, and edge cases. An agent can correctly invoke it and interpret results without additional documentation.

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 provides no description for the 'query' parameter (0% coverage), so the description's mention that it is a case-insensitive search term adds essential meaning. It doesn't elaborate on syntax or accepted formats, but for a single free-text parameter this is adequate.

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 action (search the map), enumerates the exact four parts covered, explicitly excludes relations, and names alternatives (get_object, route). This distinguishes it clearly from sibling tools.

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

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

Directly states 'Relations are NOT searched' and points to get_object and route as the correct tools for that case, giving explicit when-not guidance. Also explains the 50-document cap and truncation behavior, clarifying expected results.

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