VEDUTUM

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false; the description adds real value on top by specifying exactly what is destroyed ("Replaces an earlier layout on those faces") and how to recover it, and by disclosing the return values and that the call costs no points. It stops short of saying what happens when no qualifying roof face 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 primary action is front-loaded in the first sentence, and each subsequent sentence carries a distinct fact (remove mode, undo path, not-a-forecast caveat, point cost). The first sentence is heavily loaded with qualifiers, which slightly hurts readability.

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

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

With no output schema, the description correctly supplies the return shape (module count, area, rated power in kWp), and annotations plus text cover the destructive/idempotent profile. Remaining gaps are edge-case behavior (no qualifying faces, interaction with existing non-solar geometry) rather than anything blocking a correct call.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds behavioral meaning the schema does not: it explains that the same tool has a removal mode ("Or removes them") and ties the kind enum to the physical resource being laid out. The language parameter and the south vs. eastWest distinction are left entirely to 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 states a specific verb and resource ("Lays out photovoltaic modules... on every roof face") plus the placement rule (non-north faces, edge margins, racks on flat roofs) and the return payload. The clause "A layout, not a yield forecast" cleanly separates it from vedutum_sun_and_shadow without needing 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?

Usage context is clear: it applies to roof faces not facing north and defaults to a south-facing rack layout on flat roofs. It names vedutum_undo_last_change as the revert path, but gives no explicit "use this instead when..." routing against siblings such as vedutum_set_design or vedutum_sun_and_shadow.

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, and the description adds a genuinely useful behavioral fact not derivable from them: 'Nothing is uploaded.' It also frames the operation as a rules check against VEDUTUM's upload rules. It does not say what the verdict looks like (pass/fail plus reasons) or what the actual thresholds are, which keeps it below 5.

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

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

Two sentences, front-loaded with the core action, then the use cases, then the reassurance about no upload. No filler; every clause carries information an agent needs.

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 7 parameters, annotations, and no output schema, the description covers what is checked, when to call it, and that nothing is uploaded. The notable gap is the return value: an agent cannot tell from the text whether it gets a boolean verdict, a list of failed rules, or remediation advice, which matters for a validation tool with no output schema.

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 every parameter is already documented, and the baseline is 3. The description's list of check dimensions loosely maps to the boolean parameters (scan or vector, scale, title block), which gives mild conceptual framing but no syntax, defaults, or edge-case guidance 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?

States a precise verb (checks) and resource (a floor plan file) and enumerates exactly what is validated: file type, size, pages, scan vs vector, scale, title block. This is clearly a pre-upload validation gate, distinguishable from content-reading siblings such as vedutum_read_floor_plan or rendering-related tools like vedutum_print_resolution.

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 two concrete triggering questions: which format to export from a named set of CAD tools (Archicad, Revit, AutoCAD, Vectorworks), and whether a scan or photo of a plan is acceptable. It does not name an alternative tool or state when-not to use this one, 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 establish that this is a non-read-only, non-destructive, non-idempotent, open-world operation. The description adds useful non-obvious behavior: it creates an empty project, triggers an address lookup for sun/surroundings, returns an id and upload link, and costs no points.

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 short sentences are front-loaded with the action, followed by return and cost details without repetition. There is no filler and every sentence adds useful information.

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

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

There is no output schema, so the description usefully explains the return values: the project id and the floor-plan upload link. Combined with full schema coverage and annotations, it provides enough context to call 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 description coverage is 100%, so title, address, language, and client_name are already well documented in the schema. The description adds that client and address are optional and that address drives a sun/surroundings lookup, but it omits title and language semantics, so it remains baseline-plus rather than comprehensive.

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: 'Creates a new, empty project in the connected account.' It adds scope and optional inputs, and the 'new/empty' wording distinguishes it from get/list/project-management siblings.

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

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

It gives clear context for creation: a new empty project, optionally with client and site address. However, it does not explicitly name alternatives such as list_projects or example_project, nor state when not to use it.

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 cover the safety profile (read-only, idempotent, non-destructive), and the description adds genuinely new behavioral facts: the answer is a point count with a breakdown, and which artifacts consume no points. The remaining gap is that nothing explains the magnitude/scale of the returned number or whether the estimate is deterministic across calls.

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 pricing-relevant details in descending importance. It is dense (three quality tiers, pixel sizes, video duration in one sentence) but every clause carries cost-relevant information; only the parenthetical pixel approximations verge on clutter.

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 9 optional parameters, 100% schema coverage, no output schema, and full annotations, the description supplies the missing pieces: what is charged, what is free, and what the return looks like (points plus breakdown). An agent can call this correctly without further 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?

Schema coverage is 100%, so the baseline is 3, but the description earns elevation by glossing the quality levels (hd ≈ 1,024 px, praesentation ≈ 2,048 px, druck ≈ 4,096 px) and the 8-second video length, which the schema does not restate. It doesn't describe `storeys` or `check_run` beyond the schema, but those are already well documented.

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?

Opens with a specific verb+resource: "Counts the points VEDUTUM needs for a job," then enumerates exactly which inputs are costed. It stops short of naming a sibling tool, so an agent must infer the routing, but the scope is unmistakable.

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?

"Use when someone asks what a set of renderings or videos takes" gives a clear trigger, and the closing clause that the 3D model, share page and exports need none effectively carves out what this tool is NOT for. No explicit alternative tool is named, but the inclusion/exclusion boundary is stated.

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 genuinely new context — that the project is fictional and the response is a fixed demo packet with captions — which tells the agent this is illustrative content, not live client data. It does not state whether the response is static or regenerated, but the annotations carry the rest.

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 resource identity, then the payload, then the trigger. No redundant restatement of the name or title.

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 convey what comes back, and it does so concretely (share page, demo, five captioned images). It stops short of describing response shape or size, which leaves a small gap for an agent deciding how to consume the result.

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

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

There is only one optional parameter and schema description coverage is 100%, including the enum values and the 'de' default. The description says nothing about the language parameter, so it adds no meaning beyond the schema; 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 (returns VEDUTUM's example project „Haus Lindenweg“) and enumerates the concrete payload: share page, step-by-step demo, five captioned pictures. An agent can distinguish this from data-bearing siblings like vedutum_get_project or vedutum_list_projects purely from the 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?

Gives an explicit trigger condition — 'Use when someone wants to see what the result looks like.' That is a clear use case, but it names no alternatives or exclusions, so the agent must infer whether to prefer vedutum_get_started or vedutum_share_link.

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 destructiveHint=true and idempotentHint=false; the description adds real value by stating the change is undoable via vedutum_undo_last_change and that it costs no points, which materially affects tool choice. It does not describe what the model looks like after furnishing or the response content, leaving a small 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 short sentences, each carrying distinct information: the behavior, the scope/mode options, and the side effects (undo path, point cost). Front-loaded with the core action and free of repetition or 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 six-parameter mutation tool with no output schema and destructive annotations, the description covers behavior, scope, and reversibility well. What an agent still cannot predict is what the call returns (per-room results, counts, errors for unmatched room names), which matters given the language parameter references 'the answer'.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds context the schema lacks: that furniture is chosen by room type, that areas are kept clear of doors/windows and passages, and that scope can be a single named room, a storey, or the entire house. It does not clarify the terraces or language parameters beyond what the schema already says.

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

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

The description names a specific verb (place furniture) and resource (rooms of a project's model) and adds concrete operating constraints: room-type mapping, clearance from doors and windows, 90 cm passages. No sibling tool competes with this function, so the agent can distinguish it immediately from the other vedutum 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?

It clearly explains scope selection (one room by name, a whole storey, or the whole house) and the add-vs-replace choice, which is the main decision an agent faces here. It stops short of stating when not to use the tool or what prerequisites exist (e.g. that a floor plan must be read first), so it is strong but not exhaustive 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 readOnly, idempotent, non-destructive, closed-world, so safety needs no restating. The description adds genuinely new behavioral context: it also reports floor plan reading state "also while it runs", telling the agent that in-progress work is observable rather than an error. It does not mention error cases for unknown/inaccessible project ids.

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 a scannable enumeration of returned data, then the usage directive. The return-content list is long but each item is a distinct payload field, so it earns its space; a single comma-run sentence makes it slightly denser 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?

With no output schema, the description carries the burden of describing returns and does so field-group by field-group, plus sequencing guidance. Remaining gaps are minor: no mention of behavior for a missing/foreign project id and no note on payload size, but an agent can call this correctly from what is given.

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%: project_id's origin (vedutum_list_projects) and the language enum with default "de" are documented in the schema itself. The description adds only the loose scope hint "of the connected account" and no new format or default detail, 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 ("Returns one project of the connected account") and then enumerates the concrete contents: floor plan reading state, storeys, rooms with areas, windows/doors, roof, facade, solar modules, share link, image count, app link. This makes it trivially distinguishable from sibling reads like vedutum_list_projects or vedutum_read_floor_plan.

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 sequencing rule ("Use after vedutum_read_floor_plan to see the result") and a question-type trigger ("for questions about areas or rooms"). It lacks an explicit exclusion, e.g. when to prefer vedutum_list_projects for discovering ids or vedutum_check_floor_plan for status, 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, so the bar is lower; the description still adds content-level transparency by naming what comes back (sign-up links plus the four-step workflow) and reconfirms no state change with 'Creates nothing'.

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 short sentences, front-loaded with the returned content, then the usage cue. Nothing is padded, and the closing clause is a compact negative guarantee.

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 convey return content, and it does (links + four steps). It could go slightly further on whether the answer is prose, structured steps, or localized text, but for a read-only onboarding helper it is essentially 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?

Only one optional parameter, and the schema documents it fully (enum de/en with default 'de') at 100% coverage. The description adds no extra guidance on language selection, 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 concrete payload: 'Returns the links to open an account or sign in and the four steps from floor plan to share page.' That is far more specific than the title's 'How to start a project', and 'Creates nothing' implicitly separates it from vedutum_create_project, though no sibling is named.

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?

'Use when someone wants to try it with their own plan' gives a trigger condition, but it is loose and does not contrast with close alternatives such as vedutum_example_project (trying without own data) or vedutum_create_project (actually starting).

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 value beyond them by disclosing the returned field set, which lets an agent decide whether one call suffices. It does not mention default filtering behaviour or result-set size, which matters for an agent reasoning about completeness.

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: the first establishes scope and payload, the second establishes when to reach for it. Nothing is redundant with the title, and the usage cue is front-loaded in the second 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?

For a three-optional-parameter read tool with no output schema, naming the returned fields is exactly what the description owes. Minor gap: it does not say that archived projects are excluded by default, though the status enum documents this in the schema.

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 all three parameters are optional with documented defaults and enums, so the schema carries the semantics. The description adds nothing about limit, status, or language, which is acceptable at this coverage level but earns only the baseline.

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 ("Lists the projects in the connected VEDUTUM account") and then enumerates the return fields (id, client, floor-plan read state, last change, points left). This is clearly distinguishable from vedutum_get_project, which retrieves a single project by id.

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

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

"Use first when the person talks about one of their projects, to find its id" gives an explicit activation condition and implicitly orders it ahead of vedutum_get_project. It stops short of naming that sibling as the follow-up call or stating when not to use it (e.g. when the id is already known).

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds value by naming the data categories returned and indicating the tool is a rendering backend. It says nothing about response size, latency, or what happens when project_id is omitted, and there is no output 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?

Two efficient sentences with no redundancy, and the data inventory is front-loaded. The trailing sentence "Used by the view itself" is the weakest and is slightly vague, but it still occupies little space.

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

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

For a read-only geometry feed without an output schema, the agent would benefit from knowing the return shape or size and the consequence of omitting the optional project_id. Listing the categories helps, but expectations for the response are left largely 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 description coverage is 100%, and both parameters (language and project_id) are documented in the schema, including the enum and the reference to vedutum_list_projects. The description adds no parameter guidance, 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?

It uses a specific verb ("Returns") with a well-defined resource ("plan geometry") and enumerates the payload categories: walls, openings, rooms, furniture, roof and facade settings. That is much clearer than the sibling vedutum_get_project. However, it does not explicitly contrast with vedutum_view_model, which an agent could easily confuse with this geometry feed.

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 only usage signal is the vague sentence "Used by the view itself." It implies this is an internal consumer, but never says when an agent should call it, when it should not, or which alternative to prefer (for example, vedutum_view_model). It gives no prerequisites or conditions for use.

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 this a read-only, idempotent, non-destructive computation, so the safety burden is offloaded. The description adds value by disclosing the shape of the result: long-edge pixel count, fitting quality level, and the maximum print size per level at 300 and 150 dpi reference resolutions.

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 with no filler, and the core conversion is front-loaded. The second clause ('with the largest print each level allows at 300 and 150 dpi') is dense and slightly awkward to parse, but it carries information.

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

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

With five optional parameters, no output schema, and no required field, the description does enough by explaining what the response computes. It does not address what happens if the tool is called with no arguments (all params optional) or that the answer is localized via the language parameter.

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 real meaning by signaling that width_cm/height_cm/dpi and long_edge_px are alternative input modes ('... or a pixel width'), which the flat schema does not express. The language parameter and the 300 dpi default are left to 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?

States a specific verb (converts) with a concrete input pair (print size in cm + dpi, or a pixel width) and a concrete output (pixels on the long edge plus the fitting quality level). No sibling tool overlaps this domain, and the name/title are fully realized in the 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?

The trailing clause 'Use for brochures, boards, site hoardings, websites' gives usage contexts but not decision rules. It does not tell the agent when to pass print dimensions versus when to pass long_edge_px, nor when computing resolution is unnecessary, so the guidance is implied 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 only declare readOnly=false, openWorld=true, idempotent=false, destructive=false. The description goes well beyond them: it discloses the point cost (1 point per storey), the refusal behavior when points or the free month are exhausted, and the 1–3 minute asynchronous runtime. These are exactly the charging/latency traits an agent must know before invoking.

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 the cost/latency facts, and every clause earns its place. The opening sentence is dense, packing formats, size cap and storey cardinality into one long clause, which slightly hurts scannability but not correctness.

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 charged, multi-minute, non-idempotent operation with no output schema, it covers cost, duration, failure refusal and how to verify the result. The remaining gap is the immediate return value — it does not say what the call hands back (e.g. a job or sheet id) before the model is ready, and does not warn that re-calling costs points again.

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 all six parameters (including storey, hint, label, language) are already documented. The description adds only the file constraints for file_url and the one-storey-per-sheet rule that implicitly constrains storey; it adds no new meaning for hint, label or language. Baseline 3 is correct.

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

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

States a specific verb and resource — loads a floor plan from a public https link into a project and starts reading walls, openings and rooms into a measured model. It also scopes the input (PDF/JPG/PNG/WebP, 15 MB, one storey per sheet), so an agent can distinguish it from sibling analysis tools like vedutum_check_floor_plan without opening a schema.

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

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

Explicitly covers the when and the when-not: use a direct public https link, but "for a file on the person's computer, give them the upload link from vedutum_get_project instead." It also names the follow-up tool (vedutum_get_project) for checking the result, leaving nothing to inference.

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 what annotations cannot: the corpus is a fixed published set, answers come back as titles plus short answers plus links, and both German and English content is indexed. Rate limits and result ranking are unstated but minor for a read-only lookup.

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, capability first, applicability second, with no filler. The topical enumeration is long but each item genuinely narrows the retrieval scope, so it earns its space; a slightly tighter list would be 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?

With no output schema, the description correctly compensates by saying results are titles, short answers and links. Query semantics and corpus scope are covered; only result ordering and page-size behavior are left implicit, which is acceptable for a simple read tool.

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

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

Schema coverage is 100%, with query examples and an enum for language already documented in the schema. The description only restates the German/English duality, adding no new semantics such as how multi-word queries or the limit ceiling behave. 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 (searches) and a precisely bounded resource (VEDUTUM's published articles, service pages, feature documentation) and even names the return content. That contrasts cleanly with the sibling set, which are all action/mutation tools on projects and models.

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?

"Use for questions about architectural visualisation" plus an explicit topic list (floor plan to 3D, rendering costs, IFC/CAD, sign-off, AI labelling) tells the agent when this tool is the right entry point. It stops short of naming a when-not or an alternative tool, so it is clear context rather than a full routing rule.

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?

Adds real context beyond the annotations: partial-update semantics ('Only the values given change'), downstream effect ('every later image use them'), reversibility via undo, and zero point cost. The reversibility framing sits in mild tension with destructiveHint=true, but it clarifies rather than contradicts — the agent learns changes are scoped and undoable.

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 short sentences, front-loaded with what changes, followed by scope, persistence, and undo. No filler or 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, yet the description covers scope, persistence, reversibility, and cost — enough for a mutation tool with 10 mostly-enum parameters. It stops short of describing the response or validation/failure behavior (e.g., invalid enum values), 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?

Schema coverage is 100%, so the baseline is 3, but the description adds the crucial merge semantics — omitted fields are left untouched — which the schema does not state. It also groups the parameters conceptually (roof shape, facade material, etc.), aiding mapping, though it omits 'language' and 'project_id'.

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

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

States a specific verb ('changes the design settings') plus the exact resource and enumerates the affected attributes: roof shape, facade, frames, style, roof covering, storeys, north direction. This distinguishes it cleanly from siblings such as vedutum_set_site_address and vedutum_furnish_rooms.

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

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

Gives clear conditions and an escape hatch ('vedutum_undo_last_change goes back') plus a cost note ('Costs no points'), which helps the agent decide to use it freely. It does not, however, contrast with other design-affecting tools like vedutum_set_site_address or say when-not to use it.

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?

Goes well beyond the annotations (destructiveHint=true, openWorldHint=true) by naming exactly what is destroyed (the previous address), the recovery path (vedutum_undo_last_change), the cost (no points), the latency (~a minute), and where the result surfaces (vedutum_get_project). This is precisely the context an agent needs before invoking a destructive, slow, external-data-dependent mutation.

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 the core action first, followed by consequences, cost and recovery in descending order of importance. Every clause carries information an agent would otherwise have to guess.

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 destructive, slow, open-world mutation with no output schema, the description covers side effects, reversibility, timing, cost and result visibility. Nothing material is missing for correct invocation.

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

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

Schema description coverage is 100%, so address format, language enum and project_id sourcing are already fully documented. The description adds useful context about what the surroundings data consists of (buildings, roads, terrain; OpenStreetMap, EU-DEM) and thereby implies the meaning of the surroundings flag, but never ties that to the parameter name explicitly. 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 ("Sets the address of a project's building site") and then spells out the concrete consequences: OpenStreetMap geocoding for sun position/shadows plus loading neighbouring buildings, roads and terrain. No sibling tool does anything similar, so the agent can identify it immediately.

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

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

Gives clear operational context: it replaces the previous address, vedutum_undo_last_change reverts it, and it costs no points. It does not name an alternative tool to use instead, but no sibling overlaps this function, so the guidance is effectively complete for selection purposes.

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 this is a non-read-only, idempotent, non-destructive operation, and the description usefully explains why: the link is created on the first call and reused afterwards. It also discloses what comes back beyond the link itself (open count and approval status), which is real added context. Lacking are details on permissions or whether the link can expire or be revoked.

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?

Effectively one sentence, front-loaded with the return value, then the side effect and the supplementary data. It is slightly dense and run-on with nested clauses, but no sentence is filler.

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

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

With no output schema, the description correctly compensates by naming the returned artifacts (link, open count, approval flag) and the create-on-first-use side effect. Remaining gaps are secondary for a two-parameter tool: access requirements and link lifecycle are not covered.

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 both project_id and language documented in the schema, so the schema carries the parameter burden. The description adds nothing about either parameter, which is acceptable at this coverage level but earns only the baseline.

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 ('Returns the share link of a project') and explains what that link is: a client-facing page for viewing the model and images, commenting, and approving without an account. It is clearly distinguishable from siblings like vedutum_get_project or vedutum_view_model, though it never names an alternative 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?

Usage is implied rather than stated: the phrase 'the page where a client sees the model' signals this is the tool for client sharing, but there is no explicit 'use this when...' or any exclusion against other retrieval tools. An agent can infer the context but gets no routing rules.

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 readOnly, idempotent, openWorld and non-destructive, yet the description still adds substantive behavior: the site is geocoded through OpenStreetMap, results assume flat ground with no neighbouring buildings, and the output is explicitly not a legal shadow certificate. The only meaningful gap is error behavior when the site cannot be resolved.

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

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

Four sentences, each carrying distinct information: outputs, usage, data source, and limitations. It is front-loaded with what the tool returns. Slightly dense but no filler sentences.

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 values, and it does so explicitly (azimuth, elevation, shadow length per metre, shadow direction, sunrise/sunset). Combined with the flat-ground caveat and the OSM lookup disclosure, an agent has what it needs; only failure/edge-case behavior is unaddressed.

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 still adds value the schema does not: times are local Central European time, which resolves real timezone ambiguity, and it clarifies that building_height_m converts per-metre shadow figures into absolute lengths. That is genuine semantic addition on top of a well-documented 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 names concrete outputs (sun azimuth and elevation, shadow length per metre of building height, shadow direction, sunrise/sunset) for a specific resource: a building site on a given day. That is far beyond a restatement of the title. It does not, however, differentiate itself from a plausibly overlapping sibling such as vedutum_add_solar, 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?

It states positive usage contexts ('orientation, terrace or window planning and quick shadow questions') and a clear exclusion ('A study on flat ground without neighbouring buildings, not a legal shadow certificate'), which sets expectations about accuracy and scope. No sibling alternative is named, so it is clear context without explicit 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 declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the mutation profile is covered. The description adds genuinely new behavioral context: the undo is single-step and scoped to four specific tools, and it deliberately leaves non-assistant (in-app) changes alone. It does not say whether undo itself is reversible or what happens when no undable change 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 short sentences with zero redundancy. The core behavior and the list of affected tools come first, and the scoping caveat follows immediately.

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 agent gets no structured signal about the response, and the description does not say what an undo returns or what the failure mode is when there's nothing to undo. Given that annotations cover the destructive profile and parameters are fully documented, this is a small remaining gap rather than a blocking one.

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% — project_id ('as vedutum_list_projects returns it') and the language enum are both documented in the schema. The description adds nothing about either parameter, 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 states a specific verb ('Restores ... to the state before the last change') and resource (a project), and names the exact four sibling tools whose effects it reverts (vedutum_furnish_rooms, vedutum_set_design, vedutum_add_solar, vedutum_set_site_address). An agent can distinguish this from any other sibling without opening a schema.

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

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

'One step' and 'changes made in the app are not touched' give clear applicability conditions and an implicit exclusion: it only undoes the immediately preceding assistant-driven change, not repeated or manual edits. It stops short of stating what to do if the last change wasn't one of the four named tools, or what happens when nothing is undoable.

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 establish it as a safe, idempotent read. The description adds genuinely useful context beyond that: no account is needed for the example house, and clients without a viewer get a short textual summary instead. It doesn't disclose rendering latency or limitations of the view, so not a 5.

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

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

Two tight sentences that front-load the capability and interactions, then the sourcing rule, then the fallback return behavior. No filler or repetition of the title.

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, and the description still covers the return value: a short summary for clients without the view. Together with annotations covering safety and schema covering both parameters, an agent has everything needed 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 is 3. The description goes beyond the schema by explaining the semantic effect of project_id: omitting it selects VEDUTUM's example house, providing it selects a project of the connected account. The language parameter is left entirely to 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?

Specific verb+resource: shows a building model in 3D in the conversation, with named interactions (turn, single storeys, cut-away). It also clarifies the two sourcing modes (example house vs. account project). It doesn't explicitly contrast with sibling tools such as vedutum_model_geometry or vedutum_get_project, which keeps it from 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?

It states the conditional behavior: no project_id shows the example house with no account needed; with project_id it shows an account project. That implies when each mode applies, but there's no explicit 'use this instead of X' or prerequisite guidance relative to siblings such as vedutum_example_project or vedutum_model_geometry.

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